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Foreword 



This supplement updates the information contained in the documentation 
set of GEM® Programmer's Toolkit^"^. Recent changes to the toolkit software 
have both enhanced existing features and added new functionality. 

The GEM 3.1 Programmer's Toolkit Supplement describes the new install 
library utility (INSTLIB), new function caUs added to the GEM programming 
libraries, and updates to the GEM Applications Environment Services (AES) 
and GEM Virtual Device Interface (VDI). 

In Chapters 1 and 2 of this supplement, there is information ^bout how to 
use the new install library utility to install the sources of the new GEM bind- 
ings on your hard disk. You can choose from any of the following C lan- 
guage compilers and versions: 

• BorlandTurboC® — 1.0to2.0 

• Microsoft® C Compiler — 5.x 

• MetaWare™ High C™_ 1.4 and 1.5 

The installation utiHty also lets you select which libraries you want to install. 
How you choose to have the libraries built depends on optimization. 

Chapters 2 through 8 deal with the new function calls added to the GEM 
Programming Libraries. The library descriptions are divided into these 
categories: 

• Extended Object Library 

• Extended Raster Library 

• Transformation Library 

• Miscellaneous Library 

• DOS Library 

• Expanded Memory System (EMS) Library 

Chapters 9 through 12 contain the information required to bring the GEM 
Application Environment Services Reference Guide and the GEM Virtual 
Device Interface Reference Guide up to Release 3.1 of the GEM system 
software (GEM /3). 



GEM /3 Programmer's Toolkit Supplement iii 



Contents 



1 Installation 

Starting the Install Library Application (INSTLIB.APP) 1-1 

Selecting the Compiler 1-3 

Selecting Library Organization 1-4 

Selecting Libraries 

Installing the Libraries 1-7 

Editing PORTAB.H 1-7 

2 Compiler Notes 

Turbo C .2-1 

TURBOC.CFG(TCC Configuration File) 2-1 

Examples 2-2 

BUILTINS.MAK (MAKE Definition File) 2-3 

Microsoft C 2-4 

TOOLS.INl(MicrosoftC Initialization File) 2-4 

Examples 2-4 

INCLUDE and LIB (Microsoft C Environment Variables) 2-5 

MetaWareHighC 2-6 

MetaWareMAKE 2-6 

Runtime Startup for High CdNIT.OB J) 2-7 

CALLINT Function of MetaWare High C(CALLINT.OBJ) 2-7 

Memory Model Constraints 2-7 

Compiling the Bindings 2-8 

3 Extended Object Library 

OB.DOSTATE . 3-2 

OB.UNDOSTATE 3-3 

OBJSSTATE 3-4 

OB.DOFLAG 3-5 

OB.UNDOFLAG 3-6 

OBJSFLAG 3-7 

OB_XYWH 3-8 

OB_GET_TEXT 3-9 

OB_SET_TEXT 3-10 

OB_DRAW_DIALOG 3-11 

OB_UNDRAW_DIALOG 3-12 



GEM/3 Programmers Toolkit Supplement 



Contents 



Extended Raster Library 

RC_EQUAL 4-2 

RC_GOPY .4-3 

RC.INTERSECT . . 4-4 

RCJNSIDE 4-5 

RC_GRECT_TO_ARRAY 4-6 

Transformation Library 

X_SXFORM 5-2 

X_SASPECT 5-3 

X_YTOX 5-4 

X_UDX_XFORM 5-5 

X_UDY_XFORM 5-6 

X_DUX_XFORM 5-7 

X_DUY_XFORM 5-8 

X_UDX_SCALE 5-9 

X_UDY_SCALE 5-10 

X_DUX_SCALE . 5-11 

X_DUY_SCALE 5-12 

X_MUL_DIV 5-13 

Miscellaneous Library 

FARDR.START . 6-2 

FARDR_END 6-3 

FARDR_CS 6-4 

FORM_EXDO 6-5 

FIXJCON 6-6 

EVNT.EVENT . 6-7 

DOS Function Library 

DOS_CHDIR 7-2 

DOS_GDIR . 7-3 

DOS_GDRV 7-4 

DOS.SDRV 7-5 

DOS.SDTA 7-6 

DOS.GDTA 7-7 

DOS SnRST 7-8 



vi GEM/3 Programmers Toolkit Supplement 



Contents 



DOS.SNEXT . 7-9 

DOS.OPEN 7-10 

DOS_CLOSE 7-11 

READ_PIECE 7-12 

DOS_READ 7-13 

DOS.LSEEK 7-14 

DOS_WAIT 7-15 

DOS_ALLOC 7-16 

DOS.AVAIL 7-17 

DOS.FREE 7-18 

DOS.SPACE 7-19 

DOS_RMDIR 7-20 

DOS_CREATE 7-21 

DOS.MKDIR 7-22 

DOS_DELETE 7-23 

DOS_RENAME 7-24 

WRITE_PIECE 7-25 

DOS.WRITE 7-26 

DOS.CHMOD 7-27 

DOS.SETDT 7-28 

DOS_GETDT 7-29 

DOS.EXEC 7-30 

DOS.GETDATE 7-31 

DOS_SETDATE 7-32 

DOS.GETTIME 7-33 

DOS_SETTIME 7-34 

DOS VERSION 7-35 



EMS Library 

EMSJNST 8-2 

EMS.ERRCODE 8-3 

EMS_NUM_PAGE 8-4 

EMS_FREE_PAGE 8-5 

EMS_FRAME_SEG 8-6 

EMS_ALLOC 8-7 

EMS MAP 8-8 



GEM/3 Programmers Toolkit Supplement vii 



Contents 



EMS.FREE 8-9 

EMS.VERSION 8-10 

EMS_SAVE_MAP 8-11 

EMS_RESTORE_MAP 8-12 

EMS Error Codes 8-13 

GEM AES and VDI Update 

GEM AES Supplement 9-1 

MENU.CLICK 9-2 

MENU.BAR 9-3 

Event Library Calls 9-4 

GEM VDI Supplement 9-5 

Changes and Corrections 9-5 

GDOS Modifications 9-7 

V_OPNWK(lH) 9-9 

V JUSTIFIED (B-AH) 9-11 

Memory Form Definition Block 9-13 

VQ_EXTND(66H) 9-14 

V_PLINE(6H) and V_FILLAREA(9H) 9-16 

VSF_XPERIMETER(68H) 9-17 

V_ALPHA_TEXT(5-19H) 9-18 

.OUT File Format 9-19 

Font Header Format 9-20 

Bit Image File Format 9-22 

Bit Image File Data Format 9-23 

V.COPIES (5-lCH) 9-25 

V_ETEXT(B-BH) 9-26 

V.ORIENT (5-lB) 9-28 

V_TRAY(5-1D) 9-29 

VST_EX_LOAD_FONTS(77H) 9-30 

V_SET_APP_BUFF(FFFF-6H) 9-32 

V_BEZ_ON(B-CH) 9-34 

V_BEZ_OFF (B-CH) 9-35 

V_BEZ(6-CH) 9-36 

V BEZ FILL (9-CH) ... 9-38 



viii GEM /3 Programmers Toolkit Supplement 



Contents 



V_BEZ_QUAL(5-63H) 9-40 

VS_BKCOLOR(5-66H) 9-41 

VS_GRAYOVERRIDE(85H) 9-42 

V_PAT_ROTATE(86H) 9-43 

V_SETRGBI(5-4844H) , 9-44 

V_TOPBOT(5-4845H) 9-45 

V„PS_HALFrONE(5-20H) 9-46 

10 Files and Devices Update 

DDF Files 10-1 

Sample DDF Files t 10-4 

CNFFiles 10-7 

GEM Font Drivers 10-7 

Hewlett-Packard Soft Font Drivers 10-8 

PostScript Driver ..,..,. 10-10 

ATM Files ....,,.. 10-12 



11 GEM Setup Text Files 

GEMSETUP.MSG 11-1 

Pointer Codes 11-2 

GEMSETUP.TXT , ^ . . > . . . 11-4 

Device Names ......<•.. . . 11-7 



GEM /3 Programmers Toolkit Supplement ix 



Section 1 
Installation 



Before you can install the new libraries, you must install the GEM system 
software on your hard disk according to the instructions listed the GEM® 13 
Desktop^^ Installation Guide. Once you have successfully installed the GEM 
Desktop, you will use the GEM Install application INSTALL.APP to install 
the Install Library application (INSTLIB.APP). 

Follow these basic steps to generate GEM bindings for your compiler from 
sources. 

1. Install the GEM system software. 

2. From the GEM Desktop, run INSTALL.APP to install the Install Library 
application (INSLIB.APP). The Desktop will automatically create a folder 
(directory) called TCX)LKIT off of the root directory of the drive you 
specify. 

3. Start INSTLIB.APP. 

4. Select the compiler you want to use. 

5. Select how you want the library organized. 

6. Select the libraries you want to use. 

After the installation procedures are complete, you must edit one file 
(PORTAB.H) to ensure that the correct compiler is selected for the bindings. 



Starting the Install Library Application (INSTLIB.APP) 

Use INSTLIB.APP, the install library apphcation, to install the sources of the 
GEM bindings on your hard disk for use with your favorite compiler. 

1. Type GEM at the DOS prompt to load the GEM Desktop. 

2. Change the directory to VTOOLKTTXBINDINGS on the drive where you 
have installed the Programmer's Toolkit. 
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starting the Install Library Application (imTUB.APP) 



3. Double-click on the INSTLIB.APP icon. You will see the following screen 
displayed: 



File 


Installation INSTLIB I 








iigiSiiiwSSiiig^^^ 




110 


GEH Progranner's Toolkit 
Library Installation Utility 

KXLEASE 3 t, AUGUST «» 


;.;.;.;.;. v.;.v.;:;;v:v>.vX;:;:;>X;:;;;:;X;:;X;:;:v:v:;;v^ 


i*i:H;i::;si:;;i;i;;i^^ 


iiBBilliiiiiiiiiiiiiiiii^^^^ 








Conpiler : 

Model 

Ubraries : GEI1/3JES, GEH/3JDI, Expanded.Henory, 
Operating_Systen, Enhanced.Objects, 
Raster_Functions, Transfornations, 
Miscellaneous, 










iiiliiiiiii 






gigliljIgijgliwilKlg^^^^ 







Note the information box at the bottom of this screen. The first time you load 
INSTLIB.APP, all the libraries are installed, but the Compiler and Model 
fields are unassigned. The next time you load INSTLIB.APP, all three fields 
will be cleared so you can select new options if you have modified the bind- 
ings. 

When you are ready to select your compiler type and library model, click on 
Installation in the menu bar to see the Installation Menu. There are four com- 
mands in the Installation Menu: 

• Compiler 

• Library model 

• Libraries 

• Install 
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Selecting the Compiler 



Starting the Install Library Application (INSTUB.APP) 



If this is your first installation, you will notice that the Libraries option is 
grayed-out; this is because all the libraries will be installed for you automat- 
ically. The next time you load INSTLIB.APP, this option will be available. To 
continue with the installation process, click on the Compiler option in the In- 
stallation Menu. 

Note: The dialog handling in INSTLIB.APP differs from standard GEM 
dialog handling. INSTLIB.APP has been built with the new FORM_EXDO 
call that comes with version 3.1 of the GEM Programmer's Toolkit. With this 
new dialog handling, you can press Ctrl- A, Ctrl-B, Ctrl-C and so on to select 
buttons in dialogs. You can press Shift-Enter instead of Enter to automat- 
ically select the default button, and press the End key to automatically cancel 
the current operation. 



Selecting the Compiler 

After you select Compile* from the Installation Menu, you will see this 
dialog. 

To install the sources, 
select one of the three 
compilers by clicking on 
its button. Click on the 
compiler of your choice 
to highlight your selec- 
tion. 



II 
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yhicb C-conpiler do you want to use? 



Turbo-C 



MS-C 



High-C 



I Cancel 



OK 



Click on the OK button to 
continue; otherwise, click 
on Cancel to return to the 
ESJSTLIB Main Menu. 

After you select your compiler, it will be listed in the information box at the 
Main Menu. 
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Starting the I nstall Library Application (I NSTL IB.APP) Selecting Library Organization 



Selecting Library Organization 

From INSTLIB's Main Menu, click on Installation in the menu bar. From the 
Installation Menu, select the Library model command; you will see this 
dialog. 

Before selecting the library model, you should be aware that you will need at 
least 6 megabytes of free disk space if you select the Separated library or- 
ganization. If you select Common or Library, you will need at least 4 
megabytes of free disk space. The compile time will vary depending on your 
system configuration, but generally the compile time takes at least 1.5 hours. 
Detailed descriptions of the binding options follow this section. 

From this dialog, select how you want your library organized. Click once on 
the binding installation of your choice. Double-click on any of the three 
library buttons to see a brief description of the binding options. 

When you have finished, click on the OK button to return to the Main Menu; 
otherwise, click on the Cancel button. When you return to the Main Menu, 
the Model field in the information box will reflect your selection. 

If this is your first in- 
stallation, you are 
ready to select the In- 
stall option from the In- 
stallation Menu. When 
you click on Install, the 
installation process 
begins; INSTLIB 
provides on-screen 
messages indicating 
which files are being 
written to your hard 
disk. The sources will 
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How uould you prefer to install 
your GEt1/3-Bindings? 




1 CoPinon 1 1 Library 1 1 Separated I I 










Cancel 1 1 OK i 






_ 




_i^ 



be copied onto your hard disk in \TOOLKIT\GEMLIB in the appropriate 
subdisrectories. 

When the installation process is complete, you will see a message telling you 
to modify the PORTAB.H file. For more information, refer to "Editing POR- 
TAB.H" later in this section. 
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Selecting Library Organization Starting the Install Library Application (INSTLIB.APP) 



COMMON 



If you select COMMON, each collection of library routines are held in one 
source file; the entire GEM library will contain only seven files. This is how 
the earlier version of the toolkit handled bindings. The disadvantage of this 
method is that if you write a small application, all the AES and /or VDI func- 
tions are linked in with the application. This can cause applications to grow 
unnecessarily large because routines that are not called are still included. 

The COMMON installation requires the least disk space and compile time. 
About 24 files will be created (including header and ancilliary files). 



LIBRARY 



If you select LIBRARY, the larger sources (AESBIND and VDIBIND) are split 
into several modules containing functions that are part of a specific category 
(SHEL_???, APPL_???, and so on). Use this option to save space if you are 
not using specific libraries. If you use APPL_INIT, APPL_WRITE or any 
other APPL_ calls, then all the routines in that category will be bound to the 
application regardless of whether they are called or not. 

The LIBRARY installation is a compromise of COMMON and SEPARATE. It 
does not require a large amount of disk space and it significantly reduces 
compile time. Applications built using the libraries created with this option 
will not be fully size optimized. About 43 files will be created. 



SEPARATED 



If you select SEPARATED, all sources are split into several modules; each 
module contains one function. Only those functions that are used in the ap- 
plication source are bound to the application. This is how all standard 
libraries (like STDLIB of Microsoft C Compiler and Turbo C) are now built. 

This kind of installation requires at least 6 Megabytes of disk space and 
about one and a half hours to compile the bindings. A SEPARATED installa- 
tion provides the greatest saving in terms of smaller apphcations. About 319 
files will be created. 

Note: If disk space is an issue and you do not intend to modify the source of 
the bindings in the future, you can delete all the library source files after you 
have built your GEM /3 libraries. 



GEM /3 Progranuner's Toolkit Supplement 1-5 



Starting the Install Library Application (INSTLIBAPP) 



Selecting Libraries 



Selecting Libraries 

If this is not your first installation, you have the option of installing a subset 
of all the GEM libraries. With this feature, you can easily modify portions of 
your the bindings. During the actual installation of the libraries, you can 
choose not to overwrite the existing sources and save yourself a substantial 
amount of time. 

If you want to install all the GEM libraries or a subset, load INSTLIB.APP (as 
described in "Starting the Installation Application'' earlier in this section). 

From the DSfSTLIB Main Menu, select Installation from the menu bar. From 
the Installation Menu, click on the Libraries option. You will see this dialog. 



ID 



Digital Research - Binding- Installation 



Mhich libraries do you want 
to install? 



Cancel I 




ftll of then 



I OK I 



From this dialog, select the libraries you want to install. Select any combina- 
tion of libraries that you want. As you click on each button, it is highlighted. 
If you double-click on a button, you will see a brief description of that library. 

When you have selected all the libraries that you want to install, click on the 
OK button; otherwise, click on Cancel. 

You will return to the Main Menu. The Libraries field in the information box 
will be updated to reflect your current library selections. 
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Installing the Libraries Starting the Install Library Application (INSTUBAPP) 



Installing the Libraries 

To start the installation process, click on Install in the Installation Menu. IN- 
STLIB.APP provides complete information about what is happening as it in- 
stalls the libraries. 



Editing PORTAB.H 

When the source installation is complete, you will see a message instructing 
you to edit PORTAB.H so the bindings agree with your compiler type. From 
INSTLIB's Main Menu, select Quit from the File Menu. 

The file PORTAB.H is located in \TOOLKIT\INC. The identifier, which 
specifies the compiler in use, is located at the beginning of this file. Set 
#define for the selected compiler to 1 (one) and the other compiler's iden- 
tifiers to (zero). For example, if you selected Turbo C as your compiler, the 
identifier would look like this: 



#de£ine 


TURBO C 


1 


/♦selected*/ 


#de£ine 


MS C 





/*not selected*/ 


#define 


HIGH C 





/*not selected*/ 



Note: Remember to save PORTAB.H after you modify it. 
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Section 2 
Compiler Notes 



The following notes provide information about how to use the GEM/3 bind- 
ings with the supported compilers: 

• Turbo C 

• Microsoft C 

• HighC 



Turbo C 

Using the GEM/3 library with Turbo C is particularly well supported. To 
use the library, however, you should be aware of the following information. 

TURBOCCFG (TCC Configuration File) 

You must create a file named TURBOCCFG in the directory where you have 
installed Turbo C This file holds options and directives which are used by 
the Turbo C compiler (TCCEXE) when it is started. 

To use the GEM/3 library, TURBOCCFG must contain the following addi- 
tional directives required for GEM/ 3 programming: 

-ml or -xaa 

The -ml directive in TURBO.CFG tells TCCEXE to use the large memory 
model; -ms indicates the small memory model. It is recommended, that you 
use the large model if you are not fully f anruliar with the procedure for writ- 
ing GEM/3 applications or with operation of the GEM/3 Toolkit. 

-I? : \TOOIiKIT\INC 

Replace the question mark (?) in the preceding example with the drive letter 
that contains the GEM/3 bindings. This directive defines the include path 
that TCCEXE uses to search for header files. You can specify this directive as 
many times as necessary. You should also specify the Turbo C include direc- 
tory in TURBOCCFG (for example -I?:\TC\INCLUDE). 

Note: Be sure that PORTAB.H is not located in the Turbo C include direc- 
tory. If it is, you must either rename it or place the GEM/ 3 include directory 
in front of the Turbo C include directory. This ensures that the PORTAB.H 
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Turbo C Examples 



file that comes with your GEM/3 Programmer's Toolkit is the one you use 
for any GEM/3 development. 

-L? : \TOOLKIT\GEMLIB 

Replace the question mark (?) in the preceding example with the drive letter 
that contains the GEM/3 bindings. This directive defines the path that 
TCC.EXE uses to search for the GEM libraries. If you copy the GEM/3 
library you built to the Turbo C library directory (?:\TC\LIB), then you will 
not need to specify this line. You must specify the Turbo C library directory, 
regardless of whether you specified the GEM library directory or not. 

Note: Do not modify other lines in TURBOC.CFG if you are not familiar 
with their meanings. 

Examples 

This example lists the contents of C:\TC\TURBOC.CFG for building a large 
memory model library on Drive D with Turbo C installed on Drive C. 

-ml 

-IC:\TC\ INCLUDE 

-ID:\T00LKIT\INC 

-LC:\TC\LIB 

-LD : \TOOLKIT\GEMLIB 
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BUILTINSMAK(MAKE Definition File) Turbo C 



BUILTINS.MAK (MAKE Definition File) 

To use Turbo C's MAKE utility, you must create a file to hold the standard 
rules MAKE uses for compiling and assembling your source files. The file 
BUILTINS.MAK should be located at the same directory where your 
MAKE .EXE is located and should contain the following: 

. c . ob j : 

tec ~c $* 
.asm.obj : 

tasm $* /MX; 

Note: Be sure that the spaces before "tec" and "tasm" are created by pressing 
the tab key, not the spacebar. 

If you use Microsoft's Macro Assembler (MASM) as your assembler, replace 
the Turbo Assemblei®'s TASM command with the MASM command: 



Instead of: 
Write: 



xnasm $* /MX; 



tasm $* /MX; 



You must also modify the makefile for the Miscellaneous Library. Modify the 
line that calls the assembler for building FARDRAW.OBJ, including all text 
between the second and third slashes (/d__SMALL ) as follows. 

tasm /dTC /d SM2VLL / mx fardraw.asm fardraw.obj 
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Microsoft C TOOLS. INI (Microsoft C IniHalization File) 



Microsoft C 

Using Microsoft C with the GEM/3 library is as straightforward as using 
Turbo C. Follow the steps below so that Microsoft C can find all the required 
paths. 

TOOLS.INI (Microsoft C Initialization File) 

All Microsoft C utilities can read a common configuration file. This file is 
named TOOLS.INL The path to this file must be specified in the environment 
variable INIT. For example, if the TOOLS.INI file is in E:\MSC\BIN, the vari- 
able INIT should be set as: 

SET INIT=E : \MSC\BIN 

You can put this command in a batch file, such as AUTOEXEC.BAT. The 
TOOLS.DvJI file is created automatically when you invoke the toolkit installa- 
tion utility INSTLIB.APP in \TOOLKIT\BINDINGS. The environment vari- 
able INIT is set automatically when you start MAKELIB.BAT. 

If you have your own TOOLS-INI file that you want to use, remove 
TOOLS.INI from the GEMLIB directory and delete the following line from 
MAKELIB.BAT: 

SET INXT-\TOOLKIT\GEMLIB 

Examples 

You must edit TOOLS.INI to set the compiler switch option to correspond to 
the memory model you are building. The first example sets the compiler 
switch option in TOOLS.INI for the small memory model. 

Edit TOOLS.INI for the small memory model like this: 
[MAKE] 
. c . ob j : 

cl -C -AS -Gs -Gas -Zl -l\TOOLKIT\INC $*.C 
.asm.obj: 

inasm $* /DMSC /NX; 
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INCLUDE and UB (Microsoft C Environment Variables) 



In this example, edit TOOLS.INI for the large memory model: 

[MAKE] 
.c.obj : 

Cl -C -AL -Gs -Oas -Zl -l\TOOLKIT\INC $*.C 
.asm.obj : 

xnasm $* /DMSC /MX; 

INCLUDE and LIB (Microsoft C Environment Variables) 

You must also set the environment variables LIB and INCLUDE as follows 
so Microsoft C can find the required header files and libraries: 

SET INCLUDE = ? :\TOOIiKIT\ INC;? :\MSC\ INCLUDE 

and 

SET LIB = ? : \MSC\LIB; ? : \TOOLKIT\GEMLIB 

Replace the question mark (?) in the preceding examples with the drive letter 
that contains the header files and librariess. 

Setting environment variables can cause the operating system error, "Out of 
environment space/' If this occurs, type the following line in your CON- 
HG-SYSfile: 

SHELL=COMMAND . COM/e : 5 12 /p 

Save CONFIG.SYS and reboot your system. The SHELL command with 
these parameters specified will increase your envirorunent space, allowing 
you to set all the needed environment variables for Microsoft C. 

You must also modify the makefile for the Miscellaneous Library. Modify the 
line that calls the assembler for building FARDRAW.OBJ, including all text 
between the second and third slashes (/d SMALL ) as follows. 

masm /dMSC /d SMALL /rax. fardraw.asm fardraw.obj 
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MetaWareHighC MetaWareMAKE 



MetaWare High C 

There are a few restrictions when using this GEM/3 Programmer's Toolkit 
with the MetaWare High C compiler that are described at the end of this sec- 
tion. To use the GEM/3 bindings with MetaWare High C, you should be 
aware of the following. 

MetaWare MAKE 

Because MetaWare does not have its own MAKE utility, you will have to ob- 
tain one from another vendor. The makefiles for High C supplied with these 
GEM/3 bindings are configured for the NDMAKE utility. NDMAKE can be 
obtained from tiiese sources: 

US MAIL: D.G.Kneller 

1032 Irving Street 439 
San Francisco, CA 94122 

UUCP: ...ucbvax!ucsfcgl!kneller 

ARPANET: kneller@cgl.ucsf.edu 

BITNET: kneller@ucsfgl.BITNET 

You can use any other MAKE utility (for example Borland's or Microsoft's), 
but you will have to edit the makefiles. Refer to the makefiles for GEM/3 
bindings. Turbo C, or Microsoft C as an example. 

Before you run MAKELIB.BAT, you must set up the High C compiler. To 
configure the High C compiler, start CONFIG.EXE located in the High C 
directory. 

Specify the following settings (if necessary): 

C Meinory__model ' BIG' 

D Tpages 150 

M Ipath ' ? : \toolkit\inc\' 

J Angle-include path ' ? :\HC\INCLUDE\' 

Note: The 'BIG' memory model in High C corresponds to the 'LARGE' 
memory model in Turbo C and Microsoft C. 
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Runtime Startup for High C (INIT.OBJ) MetaVfare Hifjh C 



All the paths specified in the configuration must end with a backslash (\); 
otherwise High C will not find the paths. The question marks (?) should be 
replaced with the drive letter on which the specified directories are located. 

Runtime Startup for High C (INIT.OBJ) 

When you install your High C compiler, the runtime startup code is built for 
the MetaWare High C heap manager. Because GEM/3 also needs memory 
for resources, you must assemble the INIT.ASM file located in the directory 
\HC\UB\SRC. 

Before assembling, edit INIT.ASM to define the following macros. Both state- 
ments appear as comments in the assembler file, so be sure to remove the 
semicolon at the beginning of each line. 

;USEJDOS__ALLOC =1 

This tells High C to use the DOS alloc-functions when enlarging the heap. 

;STACK_SIZE = XXXX 

XXXX is the numl?er of bytes you want to have available for the stack. 2000 is 
a typical stack size for most applications. You must specify the size because 
the stack is not automatically aligned when High C uses the DOS functions. 

CALLINT Function of MetaWare High C (CALLINT.OBJ) 

Because Metaware High C allows functions to pop their own parameters, 
you will also have to modify CALLINT.ASM located in \HC\LIB\SRC. At 
the end of this source, you will find that callintO returns and pops two bytes 
off the stack ("return 2"). Because the functions VDI() and GEM() also pop 
their passed word, edit CALLINT.ASM and delete the digit 2 from the callint 
statement. 

Note: If you do not make this deletion, your system will crash! 

Memory Model Constraints 

MetaWare High C parses differently than Microsoft C or Turbo C by parsing 
the keyword 'far'. This makes it difficult to use High C to create GEM/3 bind- 
ings for the small memory model without editing the binding sources. 
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Compiling the Bindings Memory Model Constraints 



To avoid this restriction, modify all definitions with the keyword 'far' as 
described in the High C manual. 

Creating MetaWare High C bindings for the small memory model can be dif- 
ficult. This is due to the runtime start-up module for High C (INIT.ASM). 
EMIT. ASM does not use DOS memory functions for heap management in the 
small memory model. The bindings are created using the small memory 
model. You can also bind an application. Because INIT.ASM does not free 
any memory after loading the program, GEM is unable to obtain memory 
from DOS for resources or variable data. 



Compiling the Bindings 

After you have modified PORTAB.H, change the current directory to 
\TOOLKIT\GEMLIB and type the following command: 

MAKELIB L To build bindings for the large memory model 

MAKELIB S To build bindings for the small memory model 

This command starts MAKELIB.BAT compiles all the binding sources and 
creates the GEM library. Specifying the L or S parameter with the MAKELIB 
command changes only the name of the library (LTCGEM.LIB to 
STCGEM.LIB). 

To ensure that your compiler is building the specified memory model, 
modify either TURBOC.CFG (changing -ml to -ms) or TOOLS.INI (changing 
-AL to -AS). For examples, refer to "TURBOC.CFG" or "TOOLS.INI" earlier 
in this section for more information. 
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Section 3 

Extended Object Library 



This section describes changes and additions to the Extended Object Library 
provided with this revised GEM/3 Programmers Toolkit. The Extended Ob- 
ject Library contains utility functions for the manipulation of object struc- 
tures. 

The descriptions assume a knowledge of GEM library call structures and 
parameter conventions. For further details of these and other GEM system 
calls, refer to the GEM Application Environment Services Reference Guide . 
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OB DOSTATE 



OB_DOSTATE 

This function sets the specific state (SELECTED, HIDETREE, DISABLED, 
and so on) in the word ob_state of an object. 

Input Arguments 

tree object tree that contains the specified object 

index index of object within tree 

state state to set in ob_state 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID ob_dostate(); 
OBJECT FAR *tree; 
WORD index, state; 
ob dostate (tree, index, state) ; 
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OB UNDOSTATE 



OB^UNDOSTATE 

This function clears the specific state (SELECTED, HIDETREE, DISABLED, 
and so on) in the word ob_state of an object. 

Input Argiunents 

tree object tree that contains the specified object 

index index of object within tree 

state state to clear in ob_state 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID ob__undo8tate ( ) ; 
OBJECT FAR *tree; 
WORD index, state; 
ob_undostate(tree, index, state); 
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OB ISSTATE 



OB ISSTATE 



This function gets the state (SELECTED, HIDETREE, DISABLED, and so on) 
in the word ob_state of an object. 



Input Arguments 
tree 

index 

state 



object tree that contains the specified object 
index of object within tree 
states to be tested 



Output Arguments 
ret 



TRUE if state is set 
FALSE if state is not set 



Sample Call to C Language Binding 
WORD ob__isstate() ; 
OBJECT FAR *tree; 
WORD index, state, ret; 
ret = ob_is state (tree, index, state) ; 
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OB DOFLAG 



OB DOFLAG 



This function sets the specific flag (SELECTABLE, EXIT, TOUCHEXIT, and 
so on) in the word ob_flag of an object. 



Input Arguments 
tree 

index 

flag 

Output Arguments 



object tree that contains the specified object 
index of object within tree 
flag to set in ob_flag 



none 

Sample Call to C Language Binding 
VOID objdoflagO; 
OBJECT FAR *tzee; 
WORD index, flag; 
objdof lag (tree, index, flag) ; 
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OB UNDOFLAG 



OB^UNDOFLAG 

This function clears the specific flag (SELECTABLE, EXIT, TOUCHEXIT, and 
so on) in the word ob_flag of an object. 



Input Arguments 
tree 

index 

flag 



object tree that contains the specified object 
index of object within tree 
flag to set in ob_flag 



Output Arguments 
none 

Sample Call to C Language Binding 
VOID ob__undoflag() ; 
OBJECT FAR *tree; 
WORD index, flag; 
objindof lag (tree, index, f lag) ; 
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OB ISFLAG 



OB ISFLAG 



This function gets the flag (SELECTABLE, EXIT, TOUCHEXTT, and so on) in 
the word ob_flag of an object. 



Input Arguments 




tree 


object tree that contains the specified object 


index 


index of object within tree 


flag 


flags to be tested 


Output Arguments 




ret 


TRUE if flag is set 



FALSE if flag is not set 

Sample Call to C Language Binding 
WORD ob__isflag(); 
OBJECT FAR *tree; 
WORD index, flag; 
ret ss ob^isf lag (tree, index, flag) 
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OB XYWH 



OB.XYWH 

This function returns the x,y,w,h rectangle of a given object. The function 
takes a pointer to a structure of type GRECT; on return, this contains the 
object's current x,y,w,h parameters. 

Input Arguments 

tree object tree that contains specified object 

index index of object within tree 

prect far-pointer to a GRECT structure 

Output Argmnents 
none 

Sample Call to C Language Binding 
VOID ob__xywh() ; 
OBJECT FAR *tree; 
WORD index ; 
GRECT FAR *prect; 
ob_xywh(tree, index, prect); 
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OB GET TEXT 



OB^GET_TEXT 

This functions returns a far pointer to the string pointed to by an object struc- 
ture within a tree. The function uses the object type when returning the cor- 
rect pointer. 

Note; Objects that contain text pointers are G_TEXT, G_FTEXT, G_BOX- 
TEXT, G_FBOXTEXT, G.STREMG, G_BUTTON and G.TITLE. 

The clear parameter requests the function to initially clear the string; TRUE 
clears and FALSE leaves tiie string unchanged. 

Input Argmnents 

tree object tree that contains specified object 

index index of object within tree 

clear initially clear string? 

Output Argtunents 

ptr far-pointer that points to the (cleared) string 

Sample Call to C Language Binding 
BYTE FAR *objget_te2ct ( ) / 
OBJECT FAR *tree; 
WORD index, clear; 
BYTE FAR *ptr; 
ptr ^ ob__get_text (tree, index, clear) ; 
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OB SET TEXT 



OB SET TEXT 



This function sets the text pointer of ah required object to the ptr parameter. 
The object type is checked by the function before assigning the pointer. 

Note: Objects that contain text pointers are G_TEXT, G.FTEXT, G_BOX- 
TEXT, G_FBOXTEXT, G_STRING, G_BUTTON and G_TITLE. 



Input Arguments 
tree 

index 

ptr 



object tree that contains the specified object 
index of object within tree 
far-pointer to a string 



Output Arguments 
none 

Sample Call to C Language Binding 
VOID ob_set_text() ; 
OBJECT FAR *tree; 
WOBD index; 
BYTE FAR *ptr; 
ob_set_text (tree, index, ptr) ; 
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OB DRAW DIALOG 



OB^DRAW_DIALOG 

This function draws an entire dialog with an optional growing box. The func- 
tion takes an x,y,w,h rectangle which specifies the smallest start box of the 
growing rectangles. If the rectangle coordinates are all zero, the growing 
boxes will not be drawn. 

Input Arguments 

tree object tree to be drawn 

X, y, w, h start growing rectangle 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID objdrawjdialog ( ) ; 
OBJECT FAR *tree; 
WORD X, Yf M, h; 
objdrawjdlalog(tree, x, y, w, h) ; 
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OB UNDRAW DIALOG 



OB_UNDRAW_DIALOG 

This function removes a previously drawn dialog box from the screen and 
draws an optional shrink box. The function takes an x,y,w,h rectangle which 
specifies the smallest start box of the shrinking rectangles. If the rectangle 
coordinates are all zero, the shrinking boxes will not be drawn. 

Input Arguments 

t ree object tree to be drawn 

X, Y, w, h end shrinking rectangle 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID ob_iindraw_dialog ( ) ; 
OBJECT FAR *tree; 
WORD X, y, w, h; 
ob_undraw_dialog(tree, x, y, w, h) ; 
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Section 4 

Extended Raster Library 



This section describes modifications and enhancements to the Extended 
Raster Library provided with this revised GEM/3 Programmer's Toolkit. 
The Extended Raster library contains utility functions to manipulate coor- 
dinate structures (GRECT). 

The descriptions assume a knowledge of GEM library call structures and 
parameter conventions. For more information about these and other GEM 
system calls, refer to the GEM Applications Environment Services Reference 
Guide. 
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RC_EQUAL 



RC_EQUAL 



This function compares two rectangles to see if they are equal or not. Two 
pointers to structures of type GRECT are passed as parameters to this func- 
tion. 



In put Arguments 
precl, prec2 



pointers to structures of type GRECT 



Output Arguments 
ret 



TRUE if the rectangles are equal 
FALSE if the rectangles are not equal 



Sample Call to C Language Binding 

WORD rc^equalO; 

GRECT FAR *precl, FAR *prec2; 

ret = re equal (precl, prec2) ; 



4-2 



GEM/3 Programmer's Toolkit Supplement 



RC COPY 



RC__COPY 

This functions copies the x,y,w,h coordinates of psbox to pdbox. The 
parameters are both structures of type GRECT. This function is nothing more 
than a structure copy. 

Input Arguments 

psbox, pdbox pointer to source and destination GRECT 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID rc_jcopy(); 
GRECT FAR *psbox, FAR *pdbox; 
rc__copy (psbox, pdbox) ; 
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RC INTERSECT 



RCJNTERSECT 

This function computes the intersection of two rectangles. The intersection is 
the area that is common to both rectangles. 

The function returns TRUE, if there is a common area, and FALSE if there is 
not. If a common area exists, its coordinates are returned in the GRECT struc- 
ture p2. 



Input Arguments 
Pl 
P2 



coordinates of the first rectangle 
coordinates of the second rectangle 



Output Arguments 
ret 



TRUE if there is an intersection 
FALSE if there is no intersection 



Sample Call to C Language Binding 
WORD rc__intersect ( ) ; 
GRECT FAR *pl, FAR *p2; 
WORD ret; 
ret = rc_intersect (pl , p2) ; 



4^ 
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RC INSIDE 



RC INSIDE 



This function determines, whether a given x,y position is inside the given rec- 
tangle. If x,y is inside prec, the function returns TRUE. If not, FALSE is 
returned. 



Input Arguments 

X , y position to check 

prec pointer to rectangle coordinates 

Output Arguments 

ret TRUE if position is inside 

FALSE if position is not inside 

Sample Call to C Language Binding 
WORD xc__inside ( ) ; 
GRECT FAR *prec; 
WORD ret; 
ret ~ re inside (x, y, prec) ; 
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RC GRECT TO ARRAY 



RC^GRECT^TO^ARRAY 

11 2 2 

This function transforms the supplied absolute coordinates of an x y , x jr 
array into a x,y,w,h rectangle form. The x y , x y^ array contains the upper- 
left comer and the lower-right corner of a rectangle. 

On return from the function, prec will hold the upper-left comer and the 
width and height dimensions. 

Input Arguments 

11 2 2 
xy x y , X y^ array 

prec pointer to a stmcture of type GRECT 

Output Arguments 
none 



Sample Call to C Language Binding 
VOID rc__grect__to_array ( ) ; 
WORD FAR *xy; 
GRECT FAR *prec; 
rc_grect_to_array (prec , xy) ; 
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Section 5 
Transformation Library 



This section describes enhancements and modifications to the Transfonna- 
tion Library provided with this revised GEM/3 Programmer's Toolkit. The 
Transformation library contains utility calls for manipulating coordinate sys- 
tems. 

The descriptions assume a knowledge of the GEM library call structures and 
parameter conventions. For further details of these and other GEM system 
calls, refer to the GEM Application Environment Services Reference Guide. 
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X SXFORM 



X_SXFORM 

This function initializes the transformation library. A call to this function is 
required before using the transformation calls, otherwise unpredictable 
values will be returned. 

The transformation library can be used for calculating the differences be- 
tween device dependent coordinate and user coordinate systems. This call to 
x_sxform sets up both coordinate systems. 

Input Arguments 

user_x, user__y, user_w, user_h 

x,y,w,h rectangle which defines user coordinate space 

devjx, dev_y, dev_w, dev_h 

x,y,w,h rectangle which defines device coordinate space 

wjmicrons, hjBiicrons 

width and height of a pixel in microns (found in 
work_out[3] and work_out[4]). For more information, refer 
to V_OPNWK in the GEM Virtual Device Interface Reference 
Guide. 

Output Arguments 

ret TRUE if initialization is successful 

FALSE if initialization fails 

Sample Call to C Language Binding 

WORD x_sxform() ; 

WORD user_jic, userjf, user__w, user_h; 

WORD dev_x, dev__y, dev_w, dev_h; 

WORD w_microns , h_microns ; 

x_sxform(user_x, user,_y, user_w, user_h, devjx, dev_y, 
dev__w, dev__h, w_niicrons, h__microns) ; 



5-2 GEM/3 Programmer's Toolkit Supplement 



X SASPECT 



X^SASPECT 

This function matches an aspect ratio on the device with one specified in 
user units. The match is done in physical units rather than pixels, so a square 
specified in user units will look square when displayed on the device. Cal- 
culating the aspect ratio match in this manner compensates for devices 
which have non-square pixels. 

Input Aiffliments 

user_w , user__h width and height in user coordinates 

Output Arguments 

devjw, devjh width and height in device coordinates 

Sample Call to C Language Binding 
WORD ac__saspect ( ) ; 
WORD user__w, user_h; 
WORD *dev__w, *dev_h; 
x__saspect (user__w, userjh, devjw, dev__h) ; 
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X YTOX 



XJYTOX 

This function returns the number of pixels in the x direction physically equal 
to "y" number of pixels in the y direction. 

Input Arguments 

y number of pixels in the y direction 

Output Arguments 

X number of pixels in the x direction 

Sample Call to C Language Binding 
WORD x__ytox() ; 
WORD y, x; 
X = x_^ytox (y) ; 
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X UDX XFORM 



X_UDX_XFORM 

This function transforms an x value from user space into device space. 

Input Arguments 

userjjc X coordinate of user raster 

Output Arguments 

dev__ac x coordinate of device raster 

Sample Call to C Language Binding 
WORD 3C_udJCjKform() ; 
WORD user__x, devjjc; 
devjt s= x_udbc__xform(user_x) ; 



GEM /3 Programmer's Toolkit Supplement 5-5 



X UDY XFORM 



X_UDY^XFORM 

This function transforms a y value from user space into device space. 

Input Arguments 

user_y y coordinate of user raster 

Output Arguments 

dev_j/ y coordinate of device raster 

Sample Call to C Language Binding 
WORD x_udy_xf orm ( ) ; 
WORD user_y, dev_y; 
dev_y = x_udy__xform(user_y) ; 
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X DUX XFORM 



X_DUX_XFORM 

This function transforms an x value from device space into user space. 

Input Arguments 

dev X X coordinate of device raster 



Output Arguments 

userjK X coordiiwte of user raster 

Sample Call to C Language Binding 
WORD x_jduzjx£o3na() ; 
WORD devjc, user_x; 
userjK = x_duxjxform(devjs) ; 
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X DUX XFORM 



X_DUY_XFORM 

This function transforms a y value from device space into user space. 

Input Arguments 

dev_y y coordinate of device raster 

Output Arguments 

user__y y coordinate of user raster 

Sample Call to C Language Binding 
WORD x_duy_xform() ; 
WORD dev__y, user_y; 
user_y = x_duy_jxform(dey_y) ; 
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X UDX SCALE 



X_UDX__SCALE 

This function scales an x distance from user space into device space. 

Input Arguments 

user__d3c x distance in user space 

Output Argiunents 

devjdbc x distance in device space 

Sample Call to C Language Binding 
WORD x__udx__scale() ; 
WORD userjdx, devjdx; 
dev dx = X udac scale (user dx) ; 
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X UDY SCALE 



X_UDY_SCALE 

This function scales a y distance from user space into device space. 

Input Arguments 

userjdy y distance in user space 

Output Arguments 

dev_dy y distance in device space 

Sample Call to C Language Binding 
WORD x_udy_scale ; 
WORD user_dy, dev_dy; 
dev_dy = x_udy_scale (user_dy) ; 
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X DUX SCALE 



X^DUX_SCALE 

This function scales an x distance from device space into user space. 

Input Arguments 

devjdbc x distance in device space 

Output Arguments 

user__dx x distance in user space 

Sample Call to C Language Binding 
WORD x_duac__scale ( ) ; 
WORD devjdx, user_dK:; 
user dx = X dux scale (dev dx) ; 
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X DUY SCALE 



X.DUY^SCALE 

This function scales a y distance from device space into user space. 



Input Arguments 

dev_dy y distance in device space 

Output Arguments 

userjdy y distance in user space 

Sample Call to C Language Binding 
WORD x_duy_scale ( ) ; 
WORD devjdy, user_dy; 
user_dy = x_duy_scale (dev_dy) ; 
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X MUL DIV 



X_MUL_DIV 

This function allows you to get floating point accuracy without going to the 
performance expense of floating point. 

The calculation performed is:(((na*2*in2)/dl) + l)/2 

Input Argiunents 

ml, xd2 multiplicators 

dl divisor 

Output Arguments 

result result of the above calculation 

Sample Call to C Language Binding 
WORD x_inul_jdiv ( ) ; 
WORD ml, m2, dl, results- 
result = xjrail__div(ml, xa2, dl) ; 
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Section 6 
Miscellaneous Library 



This section describes modifications and enhancements to the Miscellaneous 
Library provided with the revised GEM/3 Programmer's Toolkit. 

These descriptions assume a knowledge of the GEM library call structures 
and parameter conventions. For more information about tiiese and other 
GEM system calls, refer to the GEM Application Environment Service Reference 
Guide. 
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FARDR START 



FARDR_START 

This function allows a C programmer to use user-defined objects. For more 
detailed information about user-defined objects, refer to GEM Applications En- 
vironment Services Reference Guide. 

When using Digital Research® products X/GEM^'^ on FlexOS^'^ (and in some 
Atari® environments) the pointer to the PARMBLK structure is passed to the 
drawing code on the stack. This allows access to it as a parameter from C. 
GEM on DOS does not handle this similarly. Instead of passing the pointer 
on the stack, GEM passes it in the register pair AX:BX. 

The fardr_start() function lets you use this pointer in a C program. You 
should call this function as the first action in your drawing code. The func- 
tion will return the pointer to the PARMBLK structure so that you can assign 
its value to a local variable. The function also saves all AES registers, and sets 
the segment registers to the application's data segment. 

You must call fardr_end() before you leave your drawing code. 

Input Arguments 

none 

Output Arguments 

pb pointer to PARMBLK-structure 

Sample Call to C Language Binding 
PARMBLK FAR *f ardr_start () ; 
PARMBLK FAR *pb; 
pb = fardr_start ; 
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FARDR END 



FARDR END 



This functions restores the registers and segments previously saved by 
f ardr_start(), so that the AES finds the correct environment. 

This function directiy returns control to the AES. All statements after the call 
to fardr_end() will not be executed. 



Input Arguments 

ret return code which you want to give to the AES 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID £axdr_end() ; 
WORD ret; 
£ardr__end ( ret ) ; 
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FARDR CS 



FARDR_CS 

This function returns the code segment value of your running application. 
You will need this function when you are building small memory model ap- 
plications with Microsoft C. Microsoft C does not allow you to cast a code 
segment pointer from small to large memory model. If you want your 
source portable between different compilers and memory models, assign 
your drawing routine like this: 

#if MS_C && M_I86SM 

applblk, ab_code = MKFP (fardr_cs () , drawing_routine) ; 
#else 

applblk . ab_code = (WORD (FAR *) () )drawing_routine; 
#endif 

You will find an example of assigning your drawing rountine in this form in 
USERDEF.C 

NOTE: This function is available only in the Microsoft C GEM library. 

Input Arguments 

none 

Output Arguments 

cs_value current code segment 

Sample Call to C Language Binding 
UWORD f ardr_cs ( ) ; 
UWORD cs_value; 
CS value f ardr cs () ; 
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FORM EXDO 



FORM_EXDO 

This is nearly the original source of the AES function form_do(). It has been 
improved to allow the selection of objects by control keys. 

The function inspects the extended ob_type of an object. This should have 
been previously set with an ASCII value which corresponds to the control 
key sequence required to activate the object. 

A value of one means Ctrl- A, two means Ctrl-B, and so on. The remaining 
functionality is unchanged. For more information, refer to the source code of 
form_exdo and FDTEST.APP. Additionally, see form_do() in the GEM Ap- 
plication Environment Services Reference Guide . 

Input Argiunents 

t ree object tree containing the form to be handled 

edix first editable field 

Output Argtunents 

ret the object which caused exit from the form 

Sample Call to C Language Binding 
WORD £orm__exdo ( ) ; 
OBJECT FAR *tree; 
WORD edix; 
WORD ret; 
ret = form eacdo (tree, edix) ; 
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FIX ICON 



FIXJCON 

This function converts all icons and bit images contained in an object tree 
from device-independent to device-dependent format. 

The function takes as parameters the VDI handle of the previously opened 
screen workstation, and a pointer to the tree containing the icons and /or bit 
images. 

Inpu t Arguments 

vdi_handle VDI-handle of (virtual) workstation 

tree pointer to an object tree 

Output Arguments 
none 

Sample Call to C Language Binding 
VOID fi3c_icon(); 
WORD vdi_handle; 
OBJECT FAR *tree; 
fix icon(vdi handle, tree) ; 
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EVNT EVENT 



EVNTJVENT 

evnt_event() is a short form of the evnt_multi() call. Instead of passing a lot 
of parameters to it, you only have to pass a pointer to a structure of type 
MEVENT (See your AES.H header file for a description of this structure). 
Using evnt_event() requires you to set only the structure members that are 
used for the event you are waiting for. So if you want to receive only mes- 
sages, all you have to do is, to set 

iDevent.e_flags == MC7_MESAG; 

and 

mevent . ejooepbuf - xnsg; 

where msg should be of type WORD msg[8] 

Input Arguments 

znevent structure of type MEVENT 

Output Arguments 

event events that occurred 

Sample Call to C Language Binding 
WORD evnt_event ( ) ; 
MEVENT mevent; 
WORD events- 
event =: evnt event (fixoevent) ; 
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Section 7 

DOS Function Library 



Section 7 describes the enhancements and modifications to the DOS Function 
Library provided with the revised GEM/3 Progranuner's Toolkit. The DOS 
Function Library contains utiUty calls that let you bypass the standard C run- 
time library so your apphcations can use the DOS interface for disk I/O. 

These descriptions assume a knowledge of the GEM library call structures 
and parameter conventions. For more information about tt\ese and other 
GEM system calls, refer to the GEM Application Environment Services Reference 
Guide. 
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DOS CHDIR 



DOS^CHDIR 

Change directory. DOS-Call (hex) 3B. 

Input Arguments 

pdrvpath drive and path to be set 

Output Arguments 

ret TRUE if unable to change directory 

FALSE if change directory is successful 

Sample Call to C Language Binding 
WORD dos__chdir ( ) ; 
BYTE FAR *pdrvpath; 
WORD ret; 
ret = dos chdir (pdrvpath) ; 
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DOS GDIR 



DOS_GDIR 

Get current directory. DOS-Call (hex) 47. 

Input Arguments 

drive = default, 1 = A, 2 = B . 



Output Arguments 
pdrvpath 

ret 



pointer where path could be stored 

TRUE if get current directory fails 
FALSE if get current directory is successful 



Sample Call to C Language Binding 
WORD dos__gdir ( ) ; 
WORD drive, ret; 
BYTE FAR *pdrvpath; 
ret = dos_gdir (drive, pdrvpath); 
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DOS GDRV 



DOS.GDRV 

Get current drive. DOS-Call (hex) 19. 

Input Arguments 
none 

Output Arguments 

drive current drive (0 = A, 1 = B, ...) 

Sample Call to C Language Binding 
WORD dos_gdrv ( ) ; 
WORD drive; 
drive = dos gdrv() ; 
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DOS SDRV 



DOS__SDRV 

Set current drive. DOS-Call (hex) OE. 

Input Arguments 

drive drive to be set (0 = A, 1 = B, ...) 

Output Arguments 

ret TRUE if set current drive fails 

FALSE if set current drive is successful 

Sample Call to C Language Binding 
WORD dos__sdrv ( ) ; 
WORD drive, ret; 
ret = dos sdrv (drive) ; 
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DOS_SDTA 

DOSJSDTA 

Set disk transfer adress. DOS-Call (hex) lA. 

Input Arguments 

Idta pointer to 44 bytes space 

Output Arguments 

ret TRUE if set disk transfer address fails 

FALSE if set disk transfer address is successful 

Sample Call to C Language Binding 
WORD dos__scita ( ) ; 
VOID FAR *ldta; 
WORD ret; 
ret = dos sdta (Idta) ; 
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DOS GDTA 



DOS^GDTA 

Get disk transfer adress. DOS-Call (hex) 1 A. 

Input Arguments 
none 

Output Arguments 

Idta pointer to current disk transfer buffer 

Sample Call to C Language Binding 
VOID FAR *dos_gdta(); 
VOID FAR *ldta; 
Idta = dos gdtaO ; 
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DOS SFIRST 



DOS SFIRST 



Search first directory entry. DOS-Call (hex) 4E. 



Input Arguments 
pspec 

attr 



pointer to path and wildcard 
file attribute (must match) 



Output Arguments 
ret 



TRUE if first directory entry is not found 
FALSE if first directory entry is found 



Sample Call to C Language Binding 
WORD dos__df irst ; 
BYTE FAR *pspec; 
WORD attr, ret; 
ret = dos sfirst (pspec, attr) ; 
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DOS SNEXT 



DOS.SNEXT 

Search next directory entry. DOS-Call (hex) 4F. 

Input Arguments 
none 

Output Arguments 

ret TRUE if next directory entry is not found 

FALSE if next directory entry is found 

Sample Call to C Language Binding 
WORD dos_sneact ( ) ; 
WORD ret; 
ret = dos snext ( ) / 
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DOS OPEN 



DOS^OPEN 

Open an existing file. DOS-Call (hex) 3D. 

Input Arsuments 

pnaxne pointer to path and filename 

access = read, 1 = write, 2 = read and write 

Output Arguments 

handle handle of opened file 

Sample Call to C Language Binding 
WORD dos_open ( ) ; 
BYTE FAR *pnajtie; 
WORD access^ ret; 
handle = do s__open (pnaxne, access); 
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DOS CLOSE 



DOS_CLOSE 

Close previously opened or created file. DOS-Call (hex) 3E. 

Input Arguments 

handle handle of opened file 

Output Arguments 

ret TRUE if file is closed 

FALSE if file cannot be closed 

Sample Call to C Language Binding 
WORD dos_close(); 
WORD handle, ret; 
ret = dos close (handle) ; 
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READ PIECE 



READ_PIECE 

Read a block of maximum 65535 bytes. DOS-Call (hex) 3F. 

Input Arguments 

handle handle returned by dos_open or dos_create 

cnt number of bytes to be read 

pbuffer pointer to a buffer big enough to hold cnt bytes 

Output Argmnents 

read number of bytes that have been read 

Sample Call to C Language Binding 
UWORD read_j>iece() ; 
WORD handle; 
UWORD cnt, read; 
VOID FAR *pbuffer; 
read =: read_jpiece (handle, cnt, pbuffer); 
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DOS READ 



DOS READ 



Read a block larger than 65535 bytes. DOS_RE AD calls READ_PIECE 
several times. 



Input Arguments 

handle handle returned by dos_open or dos_create 

cnt number of bytes to be read 

pbu££er pointer to a buffer big enough to hold cnt bytes 

Output Arguments 

read number of bytes that have been read 

Sample Call to C Language Binding 
LONG dos_read(} ; 
WORD handle; 
LONG cnt, read; 
VOID FAR *pbuffer; 
read = dos_read (handle, cnt, pbuff er) ; 
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DOS LSEEK 



DOS.LSEEK 

Move file pointer. DOS-Call (hex) 42. 

Input Arguments 

handle handle of opened file 

smode = from beginning of file 

1 = from current position 

2 = from end of file 
sof St offset to be seeked to 

Output Arguments 

newofst new offset 

Sample Call to C Language Binding 
LONG dos__lseelc() ; 
WORD handle^ smode; 
LONG sofst, newofst ; 
newofst = dos Iseek (handle, smode, sofst) ; 
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DOS WAIT 



DOS_WAIT 

Get termination code of subprocess. DOS-Call (hex) 4D. 

Input Arguments 
none 

Output Arguments 

tenncode termination code 

Sample Call to C Language Binding 
WORD dos__wait ; 
WORD termcode; 
tenncode = dos wait ( ) ; 
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DOS ALLOC 



DOS^ALLOC 

Allocate memory. DOS-Call (hex) 48. 

Input Arguments 

nbytes number of bytes to be allocated 

Output Arguments 

ptr pointer to allocated memory 

Sample Call to C Language Binding 
VOID FAR *dos__alloc() ; 
LONG nbytes; 
VOID FAR *ptr; 
ptr = dos__alloc(nbyte?) ; 
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DOS AVAIL 



DOS_AVAIL 

Get amount of free memory. DOS-Call (hex) 48. 

Input Arguments 
none 

Output Arguments 

nf ree number of free bytes 

Sample Call to C Language Binding 
LONG dos__avail ( ) ; 
LONG nfree; 
nfree = dos avail(); 
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DOS_FREE 

DOS_FREE 

Free previously allocated memory. DOS-Call (hex) 49. 

Input Arguments 

ptr pointer to allocated memory 

Output Arguments 

ret TRUE if unable to free memory 

FALSE if memory is freed 

Sample Call to C Language Binding 
WORD dos_free(); 
VOID FAR *ptr; 
ret = dos free (ptr) ; 
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DOS SPACE 



DOS_SPACE 

Get disk free space. DOS-Call (hex) 36. 

Input Arguments 

drv drive to be checked 



Output Arguments 
ptotal 

pavail 

ret 



pointer to a long (holds total of disk space) 

pointer to a long (holds available disk space) 

TRUE if unable to get free disk space 
FALSE if get free disk space is successful 



Sample Call to C Language Binding 
WORD dos_space(); 
WORD drv, ret; 

LONG FAR *ptotal, FAR *pavail; 
ret = dos__space (drv, ptotal, pavail) ; 
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DOS_RMDIR 

Remove directory. DOS-Call (hex) 3A. 

Input Arguments 

ppath pointer to directory 

Output Arguments 

ret TRUE if unable to remove directory 

FALSE if directory is removed 

Sample Call to C Language Binding 
WORD dos__nndir ; 
BYTE FAR *ppath; 
WORD ret; 
ret = dos__nndir (ppath) ; 
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DOS CREATE 



DOS_CREATE 

Create a new file. DOS-Call (hex) 3C. 

Input Arguments 

pname pointer to path and filename 

attr file's attribute 

Output Arguments 

handle handle of opened file 

Sample Call to C Language Binding 
WORD dos_create ( ) ; 
BYTE FAR *pnaine/ 
WOEUD attr, ret; 
handle = dos__create (pname, attr) ; 
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DOS MKDIR 



DOS^MKDIR 

Create new directory. DOS-Call (hex) 39. 

Input Argmnents 

ppath pointer to directory's name 

Output Argmnents 

ret TRUE if unable to create directory 

FALSE if directory created 

Sample Call to C Language Bipding 
WORD dos_inkdir() ; 
BYTE FAR *ppath; 
WORD ret; 
ret = dos mkdir (ppath) / 
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DOS DELETE 



DOS.DELETE 

Delete a file. DOS-Call (hex) 41. 

Input Arguments 

pnanifi pointer to nanne of file to be deleted 

Output Arguments 

ret TRUE if unable to delete file 

FALSE if file is deleted 

Sample Call to C Language Binding 
WORD dos_delete ( ) ; 
BYTE FAR *pnaine; 
WORD ret; 
ret = dos_delete (pnaxne) ; 
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DOS RENAME 



DOS^RENAME 

Rename a file. DOS-Call (hex) 56. 



Input Arguments 
ponaxoe 

pnname 

Output Arguments 
ret 



pointer to name of file to be renamed 
new file name 



TRUE if unable to rename file 
FALSE if file is renamed 



Sample Call to C Language Binding 
WORD dos__renaiDe ( ) ; 
BYTE FAR *ponaxQe, FAR *pnnaxne; 
WORD ret; 
ret = dos_delete (ponaxoe^ pnname) ; 
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WRITE_PIECE 

Write a block of maximum 65535 bytes. DOS-Call (hex) 3F. 

Input Arguments 

handle handle returned by dos_open or dos_create 

cnt number of bytes to be written 

pbuf f e r pointer to buffer containing cnt bytes 

Output Arguments 

write number of bytes that have been written 

Sample Call to C Language Binding 
UWORD write_jpiece ( ) ; 
WORD handle ; 
UWORD cnt, write; 
VOID FMi. *pbuffer; 
write = wr it e_jpiece (handle, cnt, pbuf f er) ; 
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DOS WRITE 



Write a block larger than 65535 bytes. DOS_WRITE calls WRITE.PIECE 
several times. 



Input Arguments 

handle handle returned by dos_open or dos_create 

cnt number of bytes to be written 

pbuf f er pointer to a buffer containing cnt bytes 

Output Arguments 

write number of bytes that have been written 

Sample Call to C Language Binding 
LONG dos_write ( ) ; 
WORD handle ; 
LONG cnt, write; 
VOID FAR *pbuffer; 
write = dos__write (handle, cnt, pbuf fer) ; 
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DOS_CHMOD 

Change a file's attribute. DOS-Call (hex) 43. 

Input Arguments 

pnaume pointer to path and filename 

f unc = get attribute, 1 = set attribute 

attr files new attribute 

Output Arguments 

nattr attribute that has been set 

Sample Call to C Language Binding 
WORD dos_chmod() ; 
BYTE FAR *pnaine; 
WORD func, attr, nattr; 
nattr = dos_chmod(pnaine, func, attr) ; 
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DOS SETDT 



DOS_SETDT 

Set a file's date and time. DOS-Call (hex) 57. 



Input Arguments 




handle 


handle of file (from dos_open or dos_create) 


time 


time to be set 


date 


date to be set 


Output Arguments 





ret 



TRUE if unable to set file's date and time 
FALSE if file's date and time are set 



Sample Call to C Language Binding 
WORD dos_setdt ( ) ; 
WORD handle, date, time, ret; 
ret = dos setdt (handle, tizne, date) ; 
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DOS_GETDT 

Get a file's date and time. DOS-Call (hex) 57. 



Input Arguments 
handle 

time 

date 



handle of file (from dos_open or dos_create) 
time of file 
date of file 



Output Arguments 
ret 



TRUE if unable to get file's date and time 
FALSE if able to get file's date and time 



Sample Call to C Language Binding 
WORD dos_getdt ( ) / 

WORD handle, FAR *date, FAR *tiiae, ret; 
ret = dos get dt (handle, time, date) ; 
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DOS_EXEC 

DOS^EXEC 

Call a subprocess. DOS-Call (hex) 4B. 

Input Arguments 

pname pointer to name of file to be executed 

para pointer to parameters that should be passed 

envm segment address of environment variables 

Output Arguments 

ret TRUE if unable to call subprocess 

FALSE if subprocess is called 

Sample Call to C Language Binding 
WORD dos__exec ( ) ; 
BYTE FAR *pname; 
BYTE FAR *para; 
UWORD envm; 
WORD ret; 
ret = dos_exec (pname ^ para, envm); 



7-30 GEM /3 Programmer's Toolkit Supplement 



DOS GETDATE 



DOS_GETDATE 

Get current date. DOS-Call (hex) 2A. 



Input Arguments 




yr 


current year 


mo 


current month 


dy 


current day 


dw 


day of week (sunday = 0) 


Output Arguments 




none 




Sample Call to C Langi 


uage Binding 



VOID dos_getdate / 

WORD FAR *yr, FAR *mo, FAR *dy, FAR *dw; 

dos_getdate (yr, mo, dy, dw) ; 
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DOS SETDATE 



DOS^SETDATE 

Set date. DOS-Call (hex) 2B. 



Input Arguments 




yr 


year to be set 


no 


month to be set 


dy 


day to be set 


Output Arguments 




none 




Sample Call to C Language Binding 



VOID dos__setdate() ; 

WORD yr, mo, dy; 

dos setdate(yr, mo, dy) ; 
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DOS_GETTIME 

Get current time. DOS-Call (hex) 2C. 



Input Arguments 




hr 


current hour 


mi 


current nninute 


se 


current second 


hn 


current hundredth of a second 


Output Arguments 




none 




Sample Call to C Language Binding 



VOID dos_gettinie ( ) ; 

WORD FAR *hr, FAR *mi, FAR *se, FAR *hn; 

dos__gettizne (hr, ml, se, hn) ; 
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DOS_SETTIME 

Set time. DOS-Call (hex) 2D. 



Input Arguments 




hr 


hour to be set 


mi. 


minute to be set 


se 


second to be set 


hn 


hundredth of a second to be set 


Output Arguments 




none 




Sample Call to C Language Binding 



VOID dos_settiine() ; 
WORD hr, mi, se, hn 
dos settime(hr, mi, se, hn} ; 
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DOS_VERSION 

Get version of operating system. DOS-Call (hex) 30. 



Input Arguments 




vh 


high word of version number 


vl 


low word of version number 


oem 


OEM code 


user 


user code 


Output Arguments 




none 




Sample Call to C Language Binding 



VOID dos_version() ; 

WORD FAR *vh, FAR *vl, FAR *oeia, FAR *user; 

dos version (vh, vl, oexa, user) ; 
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Section 8 
EMS Library 



This section describes modifications and enhancements to the EMS (Ex- 
panded Memory System) Library provided with the revised GEM/3 
Programmer's Toolkit. The EMS Library contains utility calls for DOS- 
specific expanded memory management. 

The descriptions in this section assume a knowledge of the GEM library call 
structures and parameter conventions. For more information about these and 
other GEM system calls, refer to the GEM Application Environment Services Ref- 
erence Guide. 
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EMSJNST 

This functions checks whether an EMS nianager is installed or not. 

Input Arguments 
none 

Output Arguments 

ret TRUE if EMS manager is installed 

FALSE if EMS manager not present 

Sample Call to C Language Binding 
WORD enis__inst () ; 
WORD ret; 
ret = ems inst ( ) ; 
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EMS_ERRCODE 

This functions returns the error code of the last EMS operation. The descrip- 
tion of the EMS error codes is at the end of this section. 



Input Ar g uments 
none 

Output Arguments 

errcode see "EMS Error Codes" at the end of this section 

Sample Call to C Language Binding 
WORD eins_errcode () ; 
WORD errcode; 
errcode = ems errcode () ; 
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EMS_NUM_PAGE 

This function returns the number of pages that are held by the EMS 
manager. Each page has a size of 16 Kbytes. 

Input Arguments 
none 

Output Arguments 

npage s number of 1 6 Kbyte pages 



Sample Call to C Language Binding 
WORD eius_num_page ( ) ; 
WORD npages; 
npage s = eins_nuia_page ( ) ; 
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EMS_FREE_PAGE 

This function returns the number of EMS pages that are still available. 

Input Arguments 
none 

Output Arguments 

f pages number of free EMS pages 

Sample Call to C Language Binding 
WORD ems__f ree__page ( ) / 
WORD fpages; 
f pages = ems__f ree_page ( ) / 
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EMS_FRAME_SEG 

This function returns the segment address of the page frame. The page frame 
segment is the base address where four pages of 16 Kbyte memory are 
mapped. 

Input Arguments 
none 

Output Arguments 

basef rame segment address of base page frame 

Sample Call to C Language Binding 
WORD ems_f raine__seg ( ) ; 
WORD baseframe; 
baseframe = ems frame seg ( } ; 



8-6 GEM/3 Programmer's Toolkit Supplement 



EMS ALLOC 



EMS ALLOC 



This function allows allocation of memory pages in the expanded memory 
area. The function returns the EMS handle used to access allocated EMS 
memory. 



Input Arguments 
npages 



number of pages to allocate 



Output Arguments 
handle 



> Memory handle to use 

FALSE if not enough memory available 



Sample Call to C Language Binding 
WORD ems_alloc ( ) ; 
WORD npages, handle; 
handle = ems alloc (npages) ; 
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EMS MAP 



Map logical page logp belonging to handle handle to physical page physp. 



Input Argiunents 
handle 

logp 

physp 

Output Arguments 
ret 



handle returned by ems_alloc 
number of logical page to be mapped 
number of physical page to be mapped to logp 



TRUE if map is successful 
FALSE if map fails 



Sample Call to C Language Binding 
WORD ems_jnap(}; 

WORD handle, logp, physp, ret; 
ret - ems map (handle, logp, physp) ; 
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EMS_FREE 

Free all pages that belong to the specified handle. 

Input Aisuments 

handle EMS handle 

Output Arguments 

ret TRUE if all pages are freed 

FALSE if uable to free all pages 

Sample Call to C Language Binding 
WORD ems_f ree ( ) ; 
WORD handle, ret; 
ret = ems free (handle) ; 
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EMS_VERSION 

Return the version number of the EMS manager. The version number is 
returned as a two digits. For example, 35 indicates version number 3.5. 

Input Argiunents 
none 

Output Arguments 

version version number of EMS manager 

Sample Call to C Language Binding 
WORD eins_version ( } ; 
WORD version; 
version = ems version () ; 
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EMS_SAVE_MAP 

Save the state of the current mapping for a specified handle. This is useful 
when dealing with more than one handle. The function lets you save the 
mapping for different handles and then restore them as necessary. 

Input Arguments 

handle handle for which mapping should be saved 

Output Arguments 

ret TRUE if save is successful 

FALSE if unable to save 

Sample Call to C Language Binding 
WORD eins_save_map ( ) ; 
WORD handle, ret; 
ret = ems_save_inap (handle) ; 
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EMS RESTORE MAP 



EMS^RESTORE_MAP 

This is the opposite to the function EMS_SAVE_MAP. The function lets you 
restore a previously saved mapping for a specified handle. 

Input Arguments 

handle handle for which mapping should be restored 

Output Arguments 

ret TRUE if restore is successful 

FALSE if unable to restore 

Sample Call to C Language Binding 
WORD ems__restore_jtoap ( ) ; 
WORD handle; 
ret = ezas__restore__xaap (handle) ; 
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EMS Error Codes 



0x80 
0x81 
0x82 
0x83 
0x84 
0x85 
0x86 
0x87 
0x88 
0x89 
0x8A 
0x8B 
0x8C 
0x8D 
0x8E 
0x8F 



EMS manager damaged 

EMS hardware error 

unidentified error 

unknown EMM handle 

unknown EMM function 

no more EMM. handles 

restore mapping error 

more than the total number of pages requested 

more pages requested than free 

zero pages requested (only below version 4.0) 

logical page out of range 

physical page out of range 

mapping save area full 

mapping has already been saved 

restore map handle not known 

subf unction not known 
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Section 9 

GEM AES and VDI Update 

GEM AES Supplement 

This part of the supplement contains the information required to bring the 
GEM Application Environment Services Reference Guide up to Release 3.1 of the 
GEM system software (GEM/3). Changes to the GEM AES include: 

• a new call, inenu_click 

• rewording of the description of the menujbar call 

• restriction of the mouse button support of three Event Library calls 
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MENILCUCK 



MENU-CLICK 

Set or query whether menus are drop-down or pull-down. 



Input Arguments 
click 



setit 



Menu type 

Drop-down 

1 Pull-down 

Determines whether call queries or sets menu type 

Query 

1 Set new value 



Output Arguments 
retval 



Menu display mechanism 

Drop down 

1 Pull down 



Sample Call to C Binding 

WORD xDenu_click() ; 
WORD click, setit; 

retval = iBenu__click (click, setit); 



Parameter Block Binding 

Control Input 



Output 



control (0) 
control (1) 
control (2) 
control (3) 
control (4) 



37 
2 

1 





int_in(0) = click 
int_in(l) - setit 



int_out (0) =retval 
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MENU_BAR 

Activate or deactivate the application's menu bar. 

The application should always call MENU_BAR to deactivate the menu bar 
before making its APPL_EXIT call. 

Input Arguments 

showit A code for whether the menu bar is activated or deactivated 

Menu bar deactivated 

1 Menu bar activated 

t ree Address of the object tree that forms this menu 

Output Arguments 

retval A coded return message 

Error 

1 No error 



Sample Call to C Binding 

WORD menujDar ( ) ; 
WORD retval, showit; 
LONG tree; 

retval = menujbar (tree, showit); 

Parameter Block Binding 

Control Input Output 

control (0) = 30 int_in(0) = showit int_out (0)=retval 

control (1) = 1 addr_in(0) = tree 

control (2) = 1 

control (3) = 1 

control (4) = 
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Event Library Calls 

The following Event Library call parameters identify the mouse button that 
was activated at the time the user event occurred: 

• EVNT_BUTTON: the output argument pmb 

• EVNT_MOUSE: the output argument pmb 

• EVNT_MULTI: the input argument bmsk 

Note that for all these parameters, the GEM/3 system supports only the 
value 0x0001, which identifies the left mouse button. 
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GEM VDI Supplement 

This part of the supplement contains the information required to bring the 
GEM Virtual Device Interface Reference Guide up to Release 3.1 of the GEM sys- 
tem software (GEM/3). 



Changes and Corrections 

The following changes and corrections to the GEM VDI Reference Guide bring 
it up to Release 3.1 specifications: 

• GEM VDI no longer uses an ASSIGN.SYS file. You can disregard all of page 
1-4 and the top of page 1-5 (to the heading "The VDI Entry Point"). 

• The paragraph and example input in the middle of page 2-15 should be 
changed as follows: 

To load the VDI and start a VDI-only application (like a test program, 
shell, or debugger), enter the following command: 

GEMVDI -FILENAME 

• In the sample C language program (page 2-18), delete the two comment lines 
that descril)e moditying ASSIGN.S yS. In addition, the command that runs 
SAMPLE.C is gemvdi -sample . exe. 

• Correct Table 3-3 (page 3-4) as follows: 

Color index 8 is light gray. 
Color index 9 is dark gray. 
Color index 13 is dark yellow. 
Color index 14 is dark cyan. 

• On page 4-21, the definition of the radius input argument should read 
"Length of circle's radius in x-axis units." 

• On page 5-25, the function name in the last sentence of the first paragraph is 
incorrect. The correct function name is vst_load^f onts (77H) . 
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For vql_^attributes (page 8-7), the correct sample call to the C language 
binding is as follows: 

WORD vql_attributes () ; 
WORD handle , att rib [ 6 ] ; 

vql__attributes (handle, att rib) ; 

The function call vjbit__iinage (page 9-26) applies only to the printer. For 
the screen, you must use raster operations (see Section 6 of the VDI guide). 

The call v xbit_i2aage, introduced in Release 3.01, is not supported in 
Release 3.1. Support for bit image rotation is provided in part by the 
inclusion of file-to-file image rotation in OUTPUT.APP. 
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APPNAME 



parameter 



GDOS Modifications 

Command line switches have been added to the command Hne to be 
processed by GEMVDI.EXE and passed on to an application. The command 
line uses this form: 

GEMVDI APPNAME [parameter...] [/S=screen] [/M=ab] 
[/R=d.river] [/I=info__path] [/F=font_path] [-program] 

A GEM application .APP filename like DRAW or PUBLISHR. 
A filename must be given if the command line uses any of 
the parameters or switches described below. 

The name of one or more data files, which are passed as 
parameters of the first parameter specified. For example, the 
command line GEMVDI DRAW PICTXJRE . GEM Starts the 
GEM® Draw Plus^"^ application and passes to the application 
file DRAW. APP the filename PICTURE .GEM as the name of 
a file to open. 

The screen driver screen is loaded instead of the default 
screen. 

The screen driver mouse configuration bytes (port and 
mouse type) are overwritten. The port value (a) and mouse 
type (b) are both patched to zero. (See the description later 
in this supplement of the MOUSE ID field in the file GEM- 
SETUP.TXT.) 

The driver identified by driver is made resident for debug- 
ging purposes. 

The GDOS creates font cacheing information files with the 
extension .INF. If this parameter is specified, these files are 
placed in the directory inf_j3ath instead of 
\GEMAPPS\FONTS. 

Enables accessing fonts from directory f oiit_path instead 
of \GEMAPPS\FONTS. 



/S=screen 



/M=ab 



/R=driver 
/ I=inf _path 

/F=font_path 
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-program The VDI should run program instead of GEM.EXE. (In 

Release 2.2 of the VDI, the delimiter was / instead of a 
dash.) No parameters may be passed to programs that are 
EXEC'd by the GDOS in this n^nner. If this argument is not 
given, the command line runs the default program, 
GEM .EXE, passing to it any parameters on the command 
line. Note tihat switches are not passed to GEM.EXE. 



9-8 GEM/3 Programmer's Toolkit Supplement 



V^OPNWKdH) 



GEM VDI Supplement 



V_OPNWK (IH) 

(Page 3-2 of the GEM VDI Reference Guide) 

v_opnwk now provides support for run-time selection of output destination 
and page size, as well as providing feedback to the calling routine about es- 
capement text and landscape rotation capability. 



Additional Input Arguments 

work_in [11] Output device type in the low-order byte: 

File 

1 Serial port 

2 Parallel port 

3 Device-specific (direct) 
255 No change to default 

Page size index in the high-order byte: 

or 20 Letter size 

5 Half size 

10 BSsize 

30 A4size 

40 Legal size 

50 Double size 

55 Broad sheet size 

255 Use work-in [101] and work_in[102] 

Output port /name: 

If work_in [11] is set to 1 or 2, then work_in [ 12 ] con- 
tains the port number. Otherwise, work_in [ 12+] contains 
the output file name (full path) with one character per word 
and null word terminator. 



work_in[12+] 



work_in[101] 
work_in[102] 



X page size in 1 /lOO's inch 
Y page size in 1 /lOO's inch 
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Modified Output Arguiyients 

work_out [14] Set to 1 1 to indicate that escapement text is available; other- 
wise set to 10. 

work_out [24] Set to 1 1 to indicate that escapement text is the only kind of 
text available on the device; otherwise set to 10. 

work_out [44] In addition to the existing device type (0 - 4), -1 means 

landscape output can be handled by the device without rota- 
tion by the calling routine. 

Sample Call to C Language Binding 

WORD v_opnwk ( ) ; 

WORD work__in [103], work_out [57], handle / 

v_opnwk(work_in, &handle, work_out) ; 

Parameter Block Binding 

Control Input Output 

control (0) = 1 intln(n) = worK_in[n], intout (m) =wor]c^out [m] , 

control (1) = where n = thru 102 where m = thru 44 

control (2) = 6 ptsout (i)=work_out [45+i] , 

control (3) = 103 where i = thru 11 

control (4) = 45 

control (5) = 

control (6) - handle 
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V_JUSTIFIED (B-AH) 

(Page 4-27 of the GEM VDI Reference Guide) 

The mapping for unsupported characters has been changed from a question 
mark to a blank space. See the fourth paragraph on page 4-27. 

The information on page 4-28 has been changed considerably. 



Input Arguments 
handle 

word_space 



char_space 
string 

y 

length 



Device handle 

Word spacing flag: 

0x0 000 Do not modify inter- word spacing and do 
not return output information. 

0x0 001 Modify inter-word spacing but do not 
return output information. 

0x8 000 Do not modify inter-word spacing, but do 
return output information. 

x8 1 Modify inter- word spacing and return out- 
put information. 

Character spacing flag: 

0x0000 Do not modify inter-character spacing. 
0x0001 Modify inter-character spacing. 

ASCII character string 

x-coordinate of the text alignment point 

y-coordinate of the text alignment point 

Requested length of the string, in x-axis units 



Output Arguments 
char width 



Width of each character in pixels 
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Sample Call to C Language Binding 

WORD v_justified() ; 

WORD char_width (n) / 

WORD handle, x, y, length, word_space, char_space; 

BYTE string(n}; 

v_ just if led (handle, x, y, string, length, 
word_space, char__space, char_width) ; 



Parameter Block Binding 

Control Input 



Output 



lntin(0} = wor<i_space 
Intin(l) = char_space 
lntin(n+2} = stringCn] 



control (0) = 11 

control (1) = 2 

control (2) = 

control (3) = 2+n 

control (4) = if worci_space 

equals 0x0000 or 0x0001 
control (4) = n if wor<l_space 

ecjuals 0x8000 or 0x8001 



intout(O) = char_width[0] 



intout(n-l) = 

char_width [n-1] 



control (5) = 10 
control (6) = handle 



ptsin(O) = X 

ptsin(l) = y 

ptsin(2) = length 

ptsln(3) = 



Note: n represents the number of characters in the string. 
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Memory Form Definition Block 

(Page 6-2 in the GEM VDl Reference Guide) 

In the Memory Form Definition Block (MFDB), a 32-bit pointer specified as 
-IL (Oxffff:Oxffff) defines the raster area as the quarter-screen buffer and indi- 
cates that it is located in graphic memory. 

When the quarter-screen buffer is in graphic memory, the only legal source 
or destination of a bit copy operation — vro_cpyf m ( 6DH) for example — is 
the screen. In other words, if one operand of a bit copy operation is graphic 
memory, the other operand must be screen memory. 

Graphic memory is memory that is accessible to the screen driver but not to 
the operating system. Typically it is located on a graphics card. If the AES 
has allocated the quarter-screen buffer to graphic memory, applications do 
not have access to this memory. 
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VQ_EXTND (66H) 

(Page 8-14 in the GEM VDI Reference Guide) 

Additional information for the availability of the quarter-screen buffer in 
graphic memory can be obtained through vq_extnd. If the values of output 
arguments work__out [26] and work_out [27] are non-zero, they repre- 
sent the low word and high word, respectively, of the quarter-screen buffer 
size in graphic memory. 



Modified Ouput Arguments 



work_out[20] 



work_out[21] 
work_out[22] 
work_out [23] 
work__out [24] 
work_out [25] 



work_out [26] 
work_out [27] 



Extended pixel size units 

No extended precision pixel size information is 
available 

1 work__out [21] and work_out [22] give pixel 
size in 0.1 micron units 

2 work_out [21] and work_out [22] give pixel 
size in 0.01 micron units 

3 work_out [21] and work_out [22] give pixel 
size in 0.001 micron units 

Extended x dot size in work_out [20] units 

Extended y dot size in work_out [20] units 

X dots per inch 

y dots per inch 

Bit image rotation capabilities flag 

Not applicable 

1 0-, 90-, 180-, 270-degree bit image rotations 

Low word of the quarter-screen buffer size 
High word of the quarter-screen buffer size 
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workL-Out [28] bit 1 : Bezier capability 

driver has no Bezier capability 

1 driver has Bezier capability 

Sample Call to C Language Binding 

WORD vq_e3ctnd(); 

WORD handle, owflag, work-out [57] ; 

vq_extnd( handle, owflag, worl^out) ; 

Parameter Block Binding 

Control Input Output 

control (0) " 102 Intln(O) » owflag Intout (n) >= work-out [n] 

control (1) ■ where n s o thru 44 

control (2) «■ 6 pstout(m) a 

control (3) « 1 work-out [in+45] 

control (4) '■45 where m a o thru 11 

control (5) "■ 

control (6) ■ handle 



GEM/3 Programmer's Toolkit Supplement 9-15 



GEM VDI Supplement V^LINE(6H) and VJFILLAREAQH) 



V_PLINE(6H) and V_FILLAREA(9H) 

(Pages 4-4 and 4-10 in the GEM VDI Reference Guide) 

The v_pline and v_f illarea calls have been extended to allow at least 
1495 points. The actual maximum number is driver-dependent and can be 
found in work_out [14] from the extended inquire information option of 
the vq_extnd call. 

A non-zero intin count indicates the presence of a list of indices of "jump 
points/' which means that multiple disconnected polygons are supported. 
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VSF_^PERIMETER (68H) 

This call is an extension of the existing vsf_periineter call (see page 5-39 
in the GEM VDI Reference Guide) that allows line style attributes to be used 
for filled area outlines. Note that both calls use the same opcode value. They 
are differentiated from each other by the INTIN count. 



Input Arguments 
handle 

on_off 



f_or_l 



Device handle 

Perimeter visibility flag 

Turn perimeter outlining of f 

1 Turn perimeter outlining on 

- 1 Do not change perimeter outlining 

Perimeter attributes flag 

Use normal fill color for perimeter 

1 Use line style attributes for perimeter 



Output Arguments 

set_periineter Selected perimeter visibility 

Sample Call to C Language Binding 

WORD vsf_jJ5>eriineter; 

WORD set_per itneter , handle, on_off, f_or_l; 

set_per.i.Tneter = vsf_jKperiineter (handle, on_off, f__or_l) ; 



Parameter Block Binding 

Control Input 



Output 



control (0) = 104 

control (1) = 

control (2) = 

control (3) = 2 

control (4) =: 1 

control (5) = 

control (6) = handle 



intln(0} = on^off 
intin(l) = f_or_l 



intout(O) = set_periineter 
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V.^LPHA_TEXT (5-19H) 

(Page 9-31 in the GEM VDI Reference Guide) 
Additions to currently defined control sequences: 

<DC2 > 6 Begin superscript 

<DC2>7 End superscript 

<DC2>8 Begin subscript 

<DC2>9 End subscript 

<DC2 >A Begin letter-quality mode 

<DC2>B End letter-quality mode 

<DC2>C Begin expanded 

<DC2>D End expanded 

<DC2>E Begin light 

<DC2>F End light 

<DC2>G thru <DC2>V Reserved - ignored by driver 

<DC2>W Set pica 

<DC2>x Set elite 

<DC2>Y Set condensed 

<DC2>Z Set proportional 
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.OUT File Format 

In addition to the control sequences described for the v_alpha_text call, 
the .OUT file format uses the following cormnand to insert graphics into the 
output stream: 

<ESC><ESC>GEM, x, y, w, h, D : \PATHNAME\FILENAME . EXT 

<ESC> refers to ADE value 27. x, y, w, and h are given in character cell units. 
The origin of the graphics rectangle is relative to the current cursor position, 
not the top left comer of the page. 
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Font Header Format 

The following modifications and additions have been made to the Font 
Header Format (Table F-1). 



Modified Fields 



(Page F-5 in the GEM VDI Reference Guide) 
Byte Number Description 



Font identifier, if the identifier is less than or equal to 255. If 
the identifier is greater than 255, bit 5 in byte 67 should be 
set to 1 to indicate that f ull__id is used (see Flags definition 
below). In this case, bytes 110 and 111 are used as the full 
font identifier. 

Weight: 

BitO thicken (bold) 

Bitl light 

Bit 2 skew (italic) 

Bits underline 

Bit 4 outline 

Bits shadow 
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Additional Fields 

(Page F-6 in the GEM VDI Reference Guide) 

Byte Number Description 

66-67 Flags; additional values: 

Bit 4 Set if font data is paged out to disk. 
Bit 5 Set if font data in file is compressed. 
Bit 13 Set if f ull^id should be used. 
Bit 14 - 15 Reserved, must be zero. 

88-91 next__sect — If the font data is broken into multiple sec- 

tions, this pointer points to the next section. If the current 
section is the last section, set to 0. 

The data can be broken into sections in the following man- 
ner: a header identifying the characters described by the 
data in the current section, a pointer to the next section, the 
character data; a header for the next section, another pointer, 
character data; and so on. 

92 - 109 Reserved, must be zero. 

110 - 111 full_id— full identification (>256) to use when bit 13 in 
Flags is set. In this case, f ont_id in byte will be ignored. 

112 - 149 Reserved, must be zero. 

150 - 151 compressecLsize — If font data is compressed, this is the 
number of bytes of compressed font data. 
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Bit Image File Format 

(Appendix G of the GEM VDI Reference Guide) 

The description of WORD 7 of the bit image file header format (Table G-1) is 
incorrect. The table should read as follows: 

Table G-1. Bit Image File Header Format 

Word Contents 

Image file version number 

1 Header length in words 

2 Number of planes (source device bits per pixel) 

3 Pattern definition length (number of bytes) 

4 Source device pixel width (microns) 

5 Source device pixel height (microns) 

6 Scan line widtn (pixels) 

7 Number of scan lines 

8 Bit image flag 



The bit image file header (WORD 1) can be eight or nine words long. The op- 
tional ninth word allows printer drivers to support the dithered display of 
grayscale images. Drivers can accommodate files with or without the bit 
image flag. 

In files with a 9-word header, bit of word[8] has these possible values: 

1 If a multi-plane image, planes are printed as gray 
levels. 

If a multi-plane image, planes are printed as 
colors. 

If the file is not a multi-plane image, bit of word[8] has no meaning. 

In a multi-plane image with an 8- word file header (an "old-style" image file), 
colors are printed as gray levels on a monochrome device, but the mapping 
of the colors to gray levels is not specified and may be device-dependent. 

The information beginning on the next page replaces page G-2 of the GEM 
VDIR^erence Guide. 
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Bit Image File Data Format 

The bit image data is composed of descriptors for each scan Hne. (Word 7 of 
the file header tells how many scan lines are in the file.) The scan line 
descriptors are made up of the following: 

• a vertical replication count, if the scan line is followed by one or more 
identical lines 

• encoded line descriptor data for each color plane 

The vertical replication count is a WORD value formatted as follows: 

Byte Contents 






NUL 


1 


NUL 


2 


FFHex 


3 


Count 



The count indicates how many identical scan lines are defined by the descrip- 
tor data following the vertical replication count. 

The encoded data for each color plane follows the vertical replication count 
and is presented in the following order: 

first plane — red 

second plane — green 

third plane — blue 

fourth plane — gray 

Data is always provided for all bit planes defined in WORD 2 of the file 
header. The data is presented in any of three formats: 

solid_riin 

pattern._run 

bit_string 

Note: Because scan line data is encoded in byte-wide packets (groups of 
eight pixels), the number of pixels described for each bit plane of a scan line 
is always a multiple of eight, as the following example demonstrates. 
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This example is a simple illustration of the workings of the vertical replica- 
tion count and scan line descriptor data. It uses a hypothetical image file in 
which WORD 2 of the header is 00 01 (one color plane — in other words, a 
monochrome screen driver), the scan line width (WORD 6) is 00 28 (40 
pixels), and the actual image is a solid horizontal line 34 pixels long and 4 
pixels wide (four scan lines). 

00 00 FF 04 84 80 01 CO 

In the vertical replication count (00 00 FF 04), the count is 04, indicating 
that the descriptor data applies to four consecutive scan lines. The first 
descriptor (84) is a solLdirnn four bytes (32 pixels) long. The second 
descriptor (80 01 CO) is a bit_string one byte long, containing two black 
pixels and six blank pixels. The 32 pixels from the solidLrun and the two 
pixels from the bit_string add up to the 34 pixels of the solid line, and the 
remaining six pixels fill out the 40-pixel line. 

If WORD 2 of the file header had indicated four color planes, the vertical 
replication count would have been followed by descriptor pairs (solid_run 
and bit_string) for each color plane in turn. 
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V_COPIES (5-lCH) 

This escape function allows the calling routine to specify the number of 
copies to be made of each page. All pages output before the workstation is 
closed are printed with the specified number of copies. This function applies 
to printers only. 



Input Arguments 
handle 

count 



Device handle 
Number of copies 



Sample Call to C Language Binding 

WORD v_copies ( ) ; 
WORD handle, count; 

y_copies (handle, count); 



Parameter Block Binding 

Control Input 



control (0) = 5 

control (1) = 

control (2) = 

control (3) = 1 

control (4) =0 

control (5) = 28 

control (6) = handle 



Intln(O) = count 
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V_ETEXT (B-BH) 

This function writes each character of a text string relative to the specified 
starting position. It is typically used to override the driver's default method 
of justification. This function applies to printers and plotters only. 



Input Arguments 
handle 



y 

string 
offsets 



Device handle 

X-coordinate of starting position 

Y-coordinate of starting position 

Address of null-terminated text string 

Address of WORD array of position offsets 

Each offset is an x,y pair of signed integers that indicate the 
position of the next character in the string relative to the 
starting position. The first offset pair affects the position of 
the first character in the string. Some drivers ignore the y 
component of each pair, in which case y is assumed to equal 
zero. 



Sample Call to C Language Binding 

*offsets; 
v_eteact (handle, x, y, string, offsets) 



WORD v_etext ( ) ; 
WORD handle, x, y, 
BYTE *string; 



9-26 



GEM/3 Programmer's Toolkit Supplement 



V^TEXr(B-BH) 



GEM VDI Supplement 



Parameter Block Binding 
Control 



Input 



oontrol (0) = 

control (1) = 

control (2) = 

control (3) = 

control (4) = 

control (5) = 11 

control (6) — handle 



11 

length of 

string + 1 



length of 

string 





ptBln(O) >= X 

ptsin(l) = y 

ptsin(2) s offsets [0] 

ptein(3) = offsets [1] 



ptsin(2n+l) = offsets [2n-l] 
intin(O) = string [0] 



intin(n-l) = string[n-l] 
where n =: length of string 
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V^ORIENT (5-lB) 

This escape function allows the calling routine to select one of two page 
orientations: portrait (the default) or landscape. The function must be called 
before the output of any primitives or attributes. 

Input Argmnents 

handle Device handle 

orientation Page orientation 

Portrait 

1 Landscape 

Sample Call to C Language Binding 

WORD v_orient { ) ; 

WORD handle / orientation; 

v_orient (handle^ orientation) ; 

Parameter Block Binding 

Control Input 

control (0) s 5 lntin(0} = orientation 

control (1) =0 

control (2) = 

control (3) = 1 

control (4) =0 

control (5) =27 

control (6) = handle 
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V_TRAY(5-1D) 

This escape function allows the calling routine to specify a paper tray or re- 
quest manual feed. All pages output before the workstation is closed will be 
printed using the specified paper tray source. 

Input Arguments 

handle Device handle 

tray Paper tray selection: 

-1 manual feed 

default paper tray 

1 first optional paper tray 

n nth optional paper tray (n > 0) 

Sample Call to C Language Binding 

WORD v_tray() ; 
WOBD handle, tray; 

y_t ray (handle, tray) ; 

Parameter Block Binding 

Control Input 

control (0) = 5 Intln(O) = tray 

control (1) = 

control (2) = 

control (3) = 1 

control (4) = 

control (5) = 29 

control (6) = handle 
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VST_EX.LOAD JFONTS (77H) 

This function is an extension of the existing vst_loadL.f onts call (Page 3- 
18 of the GEM VDl Reference Guide), with two additional input arguments to 
provide control over font paging memory. The current defaults in units of 
paragraphs are: 

font_)cnax f ont__free 

for screens: 5120 (8 OK) 

for printers: 32767 640 (lOK) 

The GDOS attempts to allocate f ont_jnax paragraphs or all of available 
memory (whichever is smaller) less f ont__f ree paragraphs, and uses this 
amount for font paging. 

Depending on your needs, you can use either version of this call. Note that 
botih versions use the same opcode. 

Input Arguments 

handle Device handle 

select Reserved, must be zero 

f ont_jnaax Maximum number of paragraphs to allocate 

f ont__f ree Minimum number of paragraphs to leave free 

Output Arguments 

additional Number of additional font identifiers 

Sample Call to C Language Binding 

WORD vst_exL_load__f onts ; 

WORD handle, select, font_xnax, font__free; 

additional = vst__eajL_loadu_fonts (handle, select, font_jnaax, 
f ont__f ree) ; 
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Parameter Block Binding 

Control Input Output 

control (0) = 119 intln[0] = select intout(0} = additional 

control (1) = intin[l] = font_jmax 

coiit:;rol{2) = intin[2] = font_free 

control (3) = 3 

control (4) = 1 

control (5) = 

control [6] = handle 
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V_SET^PP_BUFF (FFFF-6H) 

This call reserves a memory segment for use by GDOS extensions to produce 
Bezier curves. When the application makes Bezier calls, the buffer set aside 
by this call holds the polygon generated from the Bezier anchor points and 
direction points. 

When not making Bezier calls, the application has free access to this buffer. 
A zero offset, segment, and size disable further use of this buffer and must be 
called to prevent accidental use of this memory when the application exits. 

In the absence of this call, the GDOS allocates memory via DOS calls as 
needed. The size of the buffer varies according to the complexity of the 
Bezier — ^typically around 9K bytes. 

Input Arguments 

offset Offset of buffer (first two bytes of address) 

segment Segment address of buffer (last two bytes of address) 

nparagraphs Number of paragraphs available 

Output Arguments 

address Start address of memory area 

Sample Call to C Language Binding 

VOID v_set_appjbuf f ; 
LONGWORD address ; 
WORD naparagraphs ; 

v_set_app_Jbuff (fiaddress, nparagraphs); 
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Parameter Block Binding 



Control Input 



control (0) = -1 Intin(O) = offset 

control (1) = intin(l) = segment 

control (2) = lntln(2) = nparagraphs 

control (3) = 3 

control (4) = 

control (5) = 6 

control (6) = handle 
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V_3EZ.0N (B-CH) 



V_BEZ>ON (B-CH) 

This call enables the GDOS Bezier capabilities. Note that while a handle is 
provided and the associated device driver is called, the GDOS Bezier exten- 
sion is enabled for all devices when this call is made. All current GEM 3.1 
drivers ignore this call; its only effect is within the GDOS itself. 



Input Arguments 
handle 



Device handle 



Output Arguments 
retval 



Maximum Bezier depth, a measure of the smoothness of the 
curve. The value, which can range from to 7, is an ex- 
ponent of 2, giving the number of line segments that make 
up the curve. Thus, if retval is 0, the curve is actually a 
straight line (one line segment). If retval is 7, the curve is 
made of 128 line segments. 



Sample Call to C Language Binding 

WORD vJbez_on() : 
WORD handle, retval ; 

retval = yJbez_on (handle) ; 



Parameter Block Binding 
Control 



Output 



control (0) = 11 

control <1) = 1 (indicates ON) 

control (2) =0 

control (3) =0 

control (4) = 4 

control (5) = 13 

control (6) ^s handle 



intout (0) - retval 



9-34 



GEM/3 Programmer's Toolkit Supplement 



V^EZ-OFF (B-CH) 



GEM VDI Supplement 



V^BEZ_OFF (B-CH) 

This call disables the GDOS Bezier capabilities. Any memory allocated by 
the GDOS for Bezier-generated polygons is released at this time. (See 
V_SET_APP_BUFF in this supplement for memory allocation information.) 



Input Arguments 

handle 



Device handle 



Sample Call to C Language Binding 

WORD vjDez_off(); 
WORD handle 

v_j3ez_of f (handle) ; 



Parameter Block Binding 
Control 



control (0) = 11 

control (1) = (indicates OFF) 

control (2) » o 

control (3) - 

control (4) = 

control (5) b 13 

control (6) a handle 
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V_BEZ (6-CH) 

This call draws an unfilled Bezier on the specified device. 



Input Arguments 

handle 

count 
xyarr 
bezarr 



Device handle 
Number of vertices 
Array of vertices 

Array of vertex-type flags 

bit = 1 first point in a 4-point Bezier segment (a 

curve — ^the four points are two anchor points 
and two direction points) 

bit 1=1 



jump point — a point connecting two regions 
without drawing a line between them 
("move to here" instead of "draw to here") 



Output Arguments 



npts 
nxnove 

ininy 
maxx 
maxy 



Number of points in resulting polygon 

Number of moves in resulting polygon 

Minimum x extent of rectangle ("bounding box") surround- 
ing the curve 

Minimum y extent of bounding box 

Maximum x extent of bounding box 

Maximum y extent of bounding box 



Sample Call to C Language Binding 

VOID v_bez() ; 

WORD handle, count, xyarr, extent; 

CHAR bezarr ; 

yjbez (handle, count, xyarr, bezarr, extent); 
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Parameter Block Binding 



Control 


Input 


Output 




control (0) = 6 


Intin(O) = bezarr 


intout (0) 


= npts 


control (1) = coiint 


ptsin(O) = xyarr 


intout (1) 


= nmove 


control (2) = 2 




intout (2) 


= reserved 


control (3) = (count + 


l)/2 


intout (3) 


= reserved 


control (4) = 6 




intout (4) 


= reserved 


control (5) = 13 




intout (5) 


= reserved 


control (6) = handle 




ptsout (0) 


= minx 






ptsout (1) 


= miny 






ptsout (2) 


= maxx 






ptsout (3) 


= maxy 
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V_BEZ_FILL (9-CH) 

This call draws a filled Bezier on the specified device. 



Input Arguments 




handle 


Device handle 


count 


Number of vertices 


xyarr 


Array of vertices 



bezarr Array of vertex-type flags 

bit = 1 first point in a 4-point Bezier segment (a 

curve — ^the four points are two anchor points 
and two direction points) 

bit 1 = 1 jump point — ^a point connecting two regions 

without drawing a line between them 
C'move to here'' instead of "draw to here") 



Output Arguments 



npts 

nxnove 

minx 

zniny 
maxx 
maxy 



Number of points in resulting polygon 

Number of moves in resulting polygon 

Minimum x extent of rectangle ^bounding box") surround- 
ing the curve 

Minimum y extent of bounding box 

Maximum x extent of bounding box 

Maximum y extent of bounding box 



Sample Call to C Language Binding 

VOID v_be2_fill(); 

WORD handle, coxint, xyarr, extent; 

CHAR bezarr; 

v_be2_f ill (handle, count, xyarr, bezarr, extent); 
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Parameter Block Binding 



Control 


Input 




Output 




control (0) = 9 


intin(O) 


= bezarr 


intout (0) 


= npts 


control (1) = count 


ptsin(O) 


= xyarr 


intout (1) 


= nmove 


control (2) = 2 






intout (2) 


= reserved 


control (3) = (count + 


l)/2 




intout (3) 


= reserved 


control (4) = 6 






intout (4) 


= reserved 


control (5) = 13 






intout (5) 


= reserved 


control (6) = handle 






ptsout (0) 
ptsout (1) 
ptsout (2) 
ptsout (3) 


= minx 
= miny 
s maxx 
= maxy 
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V^BEZ^QUAL (5-63H) 

This call specifies the speed/quality tradeoff parameter for Beziers. 



Input Arguments 

handle Device handle 



prcnt 



Requested speed /quality factor in percent 



Output Argxunents 

actual Actual speed /quaHty used 

Sample Call to C Language Binding 

WORD vjbez_qual() ; 

WORD (handle, prcnt, actual) ; 

v_bez__qual (handle, prcnt, actual); 



Parameter Block Binding 

Control Input 



Output 



control (0) =5 

control (1) = 

control (2) « 

control (3) = 3 

control (4) =1 

control (5) = 99 

control (6) = handle 



Intin(O) = 32 
intin(l) = 1 
intln(2) = prcnt 



intout(O) = actual 
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VS_BKCOLOR (5-66H) 

This call sets the background color for the device associated with handle, 
usually a camera device. 

Input Argmnents 

handle Device handle 

color Background color index 

Sample Call to C Language Binding 

VOID vsjDkcolor ( ) : 
WORD handle, color 

vs_j3]ccolor (handle, color); 

Parameter Block Binding 

Control Input 

control (0) s 5 Intin(O) s color 

control (1) = 

control (2) a 

control (3) » 1 

control (4) s 

control (5) » 102 

control (6) >= handle 
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VS_GRAYOVERRIDE (85H) 

This call overrides the gray level specified with the vsf_style call, patterns 
2,1 through 2,8 (see page 5^36 of the GEM VDI Reference Guide). The apphca- 
tion should specify tihe closest index in the normal fill pattern set and follow 
it with a vs__grayoverride call to "fine-tune" that gray level one devices 
that support such fine tuning. This call is currently implemented in the Post- 
Script® driver. 

Input Arguments 

handle Device handle 

grayval Gray value in tenths of a percent 

white 
1000 black 

Sample Call to C Language Binding 

VOID vs_grayoverride ( ) ; 
WORD handle, grayval; 

vs_grayoverride (handle, grayval) ; 

Parameter Block Binding 

Control 

control (0) = 133 

control (1) = 

control (2) = 

control (3) = 1 

control (4) = 

control (5) = 

control (6) = handle 
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V JPAT^ROTATE (86H) 

This call specifies pattern rotation angle. It is implemented only in printer 
drivers and is restricted to multiples of 90 degrees. 

Input Arguments 

handle Device handle 

angle Angle in tenths of a degree 

Sample Call to C Language Binding 

VOID v_pat_rotate ( ) ; 
WORD handle, angle; 

v_pat_rot ate (handle, angle) / 

Parameter Block Binding 

Control Input . 

control (0) = 134 intin(0} = angle 

control (1) = 

control (2) - 

control (3) = 1 

control (4) = 

control (5) = 

control (6) = handle 
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V_SETRGBI (5-4844H) 

This call overrides a previously set color specification with an RGB triple 
(color devices) or intensity (monochrome devices). This call is currently im- 
plemented only for the PostScript driver. 



Input Arguments 
handle 

primtype 



Device handle 

Primitive type 
17 line 
20 marker 
22 text 
25 fill 

Red component 

Green component 

Blue component 

Intensity 



Sample Call to C Language Binding 

VOID v_setrgbi(); 

WORD handle^ primtype, r, g, b, i; 

v_setrgbi (handle, primtype, r, g, b, i) ; 



Parameter Block Binding 

Control Input 



control (0) 
control (1) 
control (2) 
control (3) 
control (4) 
control (5) 
control (6) 



5 





5 



0x4844 

handle 



intln(O) = prlmt3/pe 

intin(l) = r 

lntin(2) = g 

intin(3) = b 

intin(4) = i 
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V_TOPBOT(5-4845H) 

This call is an alternative to vst_height (page 5-20 of the GEM VDI Refer- 
ence Guide). It uses top to bottom distance for text scaling, instead of top to 
baseline distance. 

Input and output arguments are the same as for vst_Jieight. 

Sample Call to C Language Binding 

VOID v_topbot() ; 

WORD handle, height, charjwidth, char_height, cell__width, 

celljheight ; 

v_topbot (handle, height, &char_width, &char_Jieight, 
&cell_width, &cell_Jieight) ; 



Parameter Block Binding 

Control Input 



Output 



control (0) = 5 

control (1) — 1 

control (2) = 4 

control (3) = 

control (4) = 

control (5) - 0x4845 

control (6) = handle 



ptsin(O) = 
ptsin(l) = height 



ptsout(0} = char_width 

ptsout (1) = charjieight 

ptsout (2) = cell_width 

ptsout (3) = cell_height 
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V_PS_HALFTONE (5-20H) 

This call controls the parameters for PostScript halftoning. It provides direct 
access to analogous PostScript language parameters. It is implemented only 
for the PostScript driver. 



Input Arguments 
handle 

index 



angle 
frequency 



Device handle 

Halftone type 

Dot screen 

1 Line screen 

2 Ellipse screen 

3 Custom (user-defined) 

Halftone screen angle 
Halftone screen frequency 



Sample Call to C Language Binding 

VOID v_j>s__halftone() ; 

WORD handle, index, angle, frequency; 

v_ps_hal ft one (handle, index, angle, frequency) 



Parameter Block Binding 
Control 



Input 



control (0) =5 

control (1) = 

control (2) =0 

control (3) = 3 

control (4) = 

control (5) = 32 

control (6) = handle 



intin(O) ^ index 
intin(l} = angle 
intln(2) = frequency 
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Files and Devices Update 

DDF Files 



Bitstream® Fontware® uses Device Description Files (DDF) to contain the 
device-dependent information that is required for generating the correct 
fonts in the correct format. DDF files also provide information about the 
device for the user-interface portion of Fontware. In the following descrip- 
tion of the fields that can occur in a DDF file, S/P indicates a field used in 
both screen and printer DDF files and P indicates a field used only in a 
printer DDF file. 



menulabel S/P unused 

xnanuf acturer S/P first part of menu label (used in the Printer Model 

menu in Fontware) 

model S/P last part of menu label (used in the Printer Model 

menu in Fontware) 

printer S/P Screen /printer flag 

screen device 

1 printer device 

hdpi S/P horizontal dots per inch 

vdpi S/P vertical dots per inch 

driverload S/P font management responsibility 

Fonts are loaded and managed by GDOS font 
manager. 

1 Device driver loads and manages its fonts. 

driver S/P Xerox® Ventura Publisher® driver name that is 

patched into the corresponding width table. This 
name should be identical to the short name in the 
zyxg patch area of the driver. See "Device 
Names" at the end of this supplement. 
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fmt 



makefon 


S/P 


usepfm 


S/P 


devkey 


S/P 



devmode 



S/P identifies screen or printer font format conversion 

program 

For example, if the value is this field is GEM, that 
identifies the font conversion program as 
CVTGEM.EXE. If the value is HPF, the conver- 
sion program is CVTHPF.EXE. The value in this 
field follows "CVT" in the conversion file pro- 
gram name. The value must be GEM if the driver 
uses the GDOS font manager. 

unused — should be zero 

unused — should be zero 

Seventh character of the font file name. By con- 
vention, a unique letter is assigned by resolution. 

S/P eighth character of the font file name 

In screen DDF files, P indicates a Portrait font and 
L and Landscape font. In printer DDF files this 
value is overridden by GENGEMIF.EXE. 



maxbmap 


S/P 


maximum size used by font conversion program 
specified by fmt (above) 


maxoffset 


S/P 


maximum offset used by font conversion pro- 
gram 


sdnoffset 


S/P 


minimum offset used by font conversion program 


xnaxcell 


S/P 


maximum size used by font conversion program 


xnaxsw 


S/P 


maximum size used by font conversion program 


gemext 


S/P 


font file extension (unused by devices that 
manage their own fonts) 


rle 


P 


run-length encoding — should be 1 


kerning 


P 


kerning flag 







no kerning 




1 


kerning 
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dtal 

dta2 

dtbl 

dtb2 

orientation 
hpjaig 

usesizes 
usebco 



P 
P 

P 
P 



Specifies the first program of the intial stage of 
font processing. Recommended value is vf ms, 
which generates Ventura width tables. 

Specifies the second program of the initial stage of 
font processing. Recommended value is vf 2wd, 
which generates Ventura width tables. 

Specifies the first program of the final stage of 
font processing. 

Specifies the second program of the final stage of 
font processing. 

generate Portrait and/or Landscape fonts 

generate Series II soft fonts (may be larger than 
255 dots) 

Not used by raster devices. 

Not used by raster devices. 



NOTE: The preferred naming convention for DDF files is that the file name 
be the value found in the gemext field. See the sample files on the following 
pages. 
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Sample DDF Files 

This is a listing of a sample DDF file for a VG A^*^-type screen driver: 

VGA. DDF 

menulabel^^vga 

zoanufactuxerssibm 

iQodel=VGA 

printer=0 

hdpi=91 

vdpi=91 

driverload=:0 

driver=VGA 

fmt=gem 

xnake£on=0 

usepfxDRO 

devke3p=v 

devinode=p 

xna3cbmap=512 

zaaxo££set=655 

zaino££set=-655 

xnaxcell=655 

xnaxsw=655 

gezne3ct=vga 
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This is a listing of a sample DDF file for an Epson® LQ-series printer. 
ELQ.DDF 

ineiiulabel=Epson LQ Series 

inanu£acturer=Epson 

model^LQ 

printez:=l 

hdpi=180 

vdpi=180 

driverload^O 

drlvers^Epson LQ 

dtal=v£ms 

dta2=v£2wd 

£mts=gem 

znake£ons=0 

usep£ni?=:0 

devkey==d 

xaazbaaap=512 

mazo££set=655 

mino££8et=-655 

maxcell-655 

maxsw=655 

gexDext^^elq 
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This is a listing of a sample DDF file for a Hewlett-Packard® LaserJet® Series 
II printer driver: 

HPH.DDF 

znenulabel=HP LaserJet Series II - HP Softfonts 

xoanufacturer^HP 

xnodel=LaserJet Series II - HP Softfonts 

printer=:l 

hdpi=300 

vdpi=300 

driverload=l 

driver=HP LJ+, 300 dpi 

dt a l=vf ms 

dta2=vf2wd 

fmt=hpf 

makefon=0 

usepfn^O 

devkeyssl 

devmode=p 

maxbmap=512 

inaxoffset=€55 

xninof f set=- 655 

inaxcell~655 

mazsw=:655 

geznext=hph 

rle=l 

keming=:l 

orientation=2 

hp_big=l 
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CNF Files 

All GEM 3.1 printer drivers read device- and system-dependent configura- 
tion files that have filenames of the form ddki . CNF. ddd is a driver identifica- 
tion taken from the driver filename, which uses the form PDddd9 . f f f . 
(f f f is a font extension like VGA or EGA.) There are three kinds of CNF 
files, used by GEM font drivers, Hewlett-Packard soft font drivers, and the 
PostScript driver. 

CNF files are pure ASCII text. Individual entries in the files use this format; 

KEYWORD (PARMl, PARM2, PARM3, . . . ) 

KEYWORD describes the function to be adjusted or included, and P ARMl 
PARM2 PARM3... are modifying or describing parameters. Parameters may 
be separated by commas. Note that both the CNF fQes themselves and all 
entries in the files are optional. 



GEM Font Drivers 

This is the format of a CNF file for a GEM font driver: 
MARGINS (XL XR YT YB) 
MARGINS Sets margins that limit graphics output to printable area. 

XL left margin in device units 
XR right margin in device units 

The XL and XR values tj^ically default to 0.5" in 
device units. For a 120 dpi printer, they would 
equal 60. 

YT top margin in device units 

YB bottom margin in device units 

The YT and YB values typically default to zero. 



GEM /3 Programmers Toolkit Supplement 10-7 



Hewlett-Packard Soft Font Drivers 



Sample DDF Files 



Hewlett-Packard Soft Font Drivers 



This is the format of a CNF file for a Hewlett-Packard soft font driver: 

M2U^INS (XL XR YT YB) 

HFI (ON__OFF) 

DOWNPATH (DIR) 

PERMFONTdD FILENAME) 

FONTSPEC (FILENAME ID SIZE ATTR MAP) 



MARGINS 



HFI 



DOHNPATH 



PERMFONT 



Same function and parameters as in GEM font driver CNF 
file. 

Flag indicating whether HP Font Information (HFI) file 
search is requested. HFI files should be located in the direc- 
tory that contains the downloadable soft fonts. 

ON__OFF = o driver search for HFI files disabled (the 
default) 

ON_OFF = 1 driver search for HFI files enabled 

Identifies directory that contains HFI files and soft font files. 

DIR Path name of directory. If a relative path 

specification is given, it is taken as relative to the 
directory that contains the driver. The default is 
".", the directory containing the driver. 

Indicates that the soft font has already been downloaded to 
the printer. In that event, the driver examines the soft font 
file for character width information but does not send the 
font down to the printer. This keyword's parameters have 
no default values. 



ID 
FILENAME 



soft font identifier 
soft font filename 
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Hewlett-Packard Soft Font Drivers 



FONTSPEC 



An alternative to HFI files. Provides the driver with infor- 
mation about a soft font that is available for downloading. 



FIT.F.NAME 


soft font filename (with no extension — 
the driver will use .SFP and .SFL) 


ID 


GEM font identifier 


SIZE 


font size in points 


ATTR = 


font attribute: Normal 


ATTR = 1 


font attribute: Bold 


ATTR = 4 


font attribute: Italic 


ATTR = 5 


font attribute: Bold Italic 


MAP - 


remap character set flag: HP character 



set 

MAP = 1 remap character set flag: GEM/Ventura 

character set 
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Sample DDF Files 



PostScript Driver 

This is the format of the CNF file used by the PostScript driver: 

MARGINS (XL XR YT YB) 

PPI (ON_OFF) 

PSFONTS (DIR) 

EOPTYPE (TYPE) 

IMGTYPE(TYPE) 

COLTYPE(TYPE) 

FONT (NAME ID ATTR MAP RESFLAG) 



MARGINS 



PFI 



PSFONTS 



EOFTYPE 



Same function and parameters as in GEM font driver CNF 
file. 

Flag indicating whether PostScript Font Information (PFI) 
file search is requested. PFI files should be located in the 
directory that contains the downloadable PostScript ASCII 
or binary format fonts. 

ON_OFF = O driver search for PFI file disabled (the 
default) 

ON_OFF = 1 driver search for PFI file enabled 

Identifies directory that contains PFI file and associated Post- 
Script downloadable font files. 

DIR Path name of directory. If a relative path 

specification is given, it is taken as relative to the 
directory that contains the driver. The default is 
"", the directory containing the driver. 

Specifies the driver method to be used for marking end of 
PostScript job/file. 

TYPE = PC Ctrl-D is appended to the PostScript out- 
put (the default) 

TYPE = MAC no characters are appended to the Post- 
Script output 
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PostScript Driver 



IMGTYPE 



COLTYPE 



FONT 



Indicates how bitmap image data is to be translated into 
PostScript. 

METHOD = COMPACT 

Image data is sent in a compressed form and is 
decoded by the PostScript interpreter. 

METHOD = FAST 

Image data is decompressed before translation to 
the appropriate PostScript string. 

Specifies to driver whether ''setrgbcolor" or "setgray" Post- 
Script functions should be used. 

COLOR Use "setrgbcolor" function (the default). 

When the COLOR parameter is set, PostScript 
handles mapping of colors to gray levels for 
monochrome printers. 

MONO Use "setgra)/' function. 

Provides an alternative to supplying a PFI file for the Post- 
Script font. 

NAME Font PostScript name 

ID GEM font identification number (for ex- 

ample, 2 = Swiss) 

ATTR = M font attribute: Normal 

ATTR = B font attribute: Bold 

ATTR = I font attribute: Italic 

ATTR s= Bl font attribute: Bold Italic 

MAP = TEXT character set re-encoding enabled 

MAP = PI character set re-encoding disabled (for 
symbol fonts) 

RESFLAG = RES font is resident 

RESFLAG = DOWN : filenazne 

Font filename must be downloaded. 
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ATM Files 

Alpha Text Mapping (ATM) files are used by non-Postscript printer drivers 
to allow device-dependent and user-dependent mapping of characters above 
the standard ASCII set. ATM files are used only for alpha text and they are 
used only when the driver attempts to output characters in the range 128- 
255. These files allow the system to use a single driver for printers with the 
same graphics mode protocol but different alpha mode protocols or 
capabilities. For example, the Hewlett-Packard Laserjet in its simplest form 
cannot print the © or ® symbols, but if fitted with a "Legal" cartridge, it can 
access tfiese characters with the appropriate escape sequence. The ATM files 
have a very simple format in which all characters are represented by their 
two-character hexadecimal representation. For example, decimal character 
128 is written as 80. The following example, taken from EHI.ATM, illustrates 
the syntax of these files: 

80 1B52015C1B5200 

81 1B52027D1B5200 

82 1B52017B1B5200 

83 61085E 

The first number on each line is the character requested by the application. 
The number sequence that follows identifies the set of characters that are 
sent to the printer. Any character without an entry is transmitted to the 
printer unchanged. In the example above, the GEM International character 
set character a — with decimal value 131 or hexadecimal value 83 — ^is trans- 
lated by the driver into the sequence 6108 5e: the character "a", a back- 
space, and the character "^". 
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GEM Setup Text Files 

The GEM Setup program uses two ASCII text files: GEMSETUP.MSG and 
GEMSETUP.TXT. This note describes the format of these two files so you 
can modify or translate the existing text files or create new ones. 

GEMSETUP.MSG 

GEMSETUP.MSG contains the messages, menus, and prompts the user sees 
while running the GEM Setup program. Here are two excerpts from this file: 

ePROMPTJPTR 
*** LINES: 4 
{ Welcome to GEM Setup! 

This program Installs 6EM/3 onto your computer. 

Do you want to install GEM/3 for the first time or change an existing 

GEM/3 installation? 
} 

eFLftB_JPIR 

The following strings are floppy disk labels. 

*** LINES: 2 

{GEM DESKTOP DISK 
GEM STARTUP DISK 
> 

The file is n\ade up of these elements: 

• A pointer code that identifies how the following text will be used. These 
ppmters are delimited by an at-sign (@) and are linked to the code in 
GEMSETUP.EXE. For that reason^lhey must not be changed. The pointer 
codes are described fully later in this note. 

• A line count indicating how many lines of text are available at this point in 
the program. For example, four hnes are available for the opening message 
and first prompt. You can change the content of these lines, but you must 
use the number of lines indicated. If you do not, all subsequent lines will be 
offset by a number of lines, and the wrong prompts and messages will appear 
on the screen. 
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Pointer Codes 



The prompt, message, or menu text that appears on the screen. This text is 
set off by braces (0 ) and must occupy the number of lines specified in the line 
count. 

Optional comment text. This text is placed between the pointer code and the 
line count and is identified by the absence of any delimiter character. 



Pointer Codes 



These are the pointer codes used by GEMSETUP.MSG: 

@PROMPT JPTR Prompts, queries, and messages that form the bulk of the 
program's interaction with the user. 

@CH0ICE_PTR Menus of options from which the user can choose. A box, 

check-mark, or other choice mechanism (it is system-depend- 
ent) apf)ears to the left of each option. 

@FOOTER_PTR Footer lines that tell the user how to select options. 

@HVOL_PTR Disk volume labels. These labels are used by the code to 

identify the disk being used for a particular operation. The 
string must be eleven characters long. If the number of char- 
acters used is less than eleven, pad the inside of the string 
with blank spaces. The first example below is correct; the 
second example is incorrect. (The first line shows the charac- 
ter count.) 



correct 
incorrect 



12345678901 
GEM SCRN 
GEM SCRN 



8HIAB_PTR 



@KEYWORDS PTR 



Disk label strings. These strings are swapped into the text of 
@PROMPT__PTR to identify for the user the disks required for 
a given operation. The XX strings are placeholders for driver 
pack label strings, which come from GEMSETUP.TXT on the 
driver pack disk. Do not translate or alter the XX strings. 

Unique characters for the GEMSETUP.TXT label strings. Do 
not translate or alter. 
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Pointer Codes 



SFLABJPTR 



@FVOL_PTR 

eCOPYJPTR 
@TOOlJ42^NY 
60 SPACE 



Floppy disk labels. These strings are swapped into the text 
of QPROMPTJPTR to identify the disks created for a floppy 
disk installation. 

Floppy disk volume labels. 

Messages displayed by the GEM Setup program. 



The example below shows the first GEM Setup screen and identifies the 
pointer codes for the types of text on the screen. 



Welcome to GEM Setup! 
This program Installs GEM/3 onto your computer. 

Do you want to Install GEM/3 for the first tine or change an existing 
6EM/3 Installation? 

[] INSTALL NEW CONFIGURATION 

[] CHANGE EXISTING CONFIGURATION 

Press T or i to move cursor, <ENTER> to choose, <ESC> to exit/cancel. 
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GEMSETUP.TXT 

The GEMSETUP.TXT file contains the strings that describe the various 
devices and their associated files. Here are two excerpts from GEM- 
SETUP.TXT: 

@ SCREEN 

{ 

I DESCRIPTION I IBM Enhanced Card & 16-Color Display (640x350) 

I SHORT DESCRIEGA HiRes 16 

I FILENAME | SDEHF8 . EGA 

iSRC DISK I GEM SCREEN DISK #1 

IFNT WILDCRD|*.EGA 

I LONG DESCRPI 

Choose this entry if your system is equipped with an IBM Enhanced 

Graphics Adapter card, with at least 128K of graphics memory on 

the card, and an IBM enhanced color display. This 16-color 

display offers a resolution of 640 horizontal by 350 vertical 

pixels. 

} 



SPRINTER 

{ 

I DESCRIPTION I Hewlett Packard Laserjet II Printer (300 x 300 Dots/Inch) 

I SHORT DESCRIHP Laser II 

I FILENAME I PDHPU8 . B3 

ISRC DISK I GEM PRINTER DISK #3 

IFNT WILDCRD|*.B30 

I LONG DESCRPI 

Choose this entry if you are using a Hewlett Packard Laserjet 

II printer. This printer offers a print resolution of 300 x 300 
dots per inch. 

} 

The descriptions are grouped according to the device: 

©METAFILE 
@ SCREEN 
@PRINTER 
QPLOTTER 

Within each category, the device descriptions are delimited by braces, as 
shown in the examples. 

Each field name is delimited by a broken vertical bar (II), which — with one 
exception — ^is followed immediately by the field content. The exception is 
the 'long description" field, whose content starts in column 1 of the next line. 
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GEMSETUP.TXT 



These are the fields used in GEMSETUP.TXT: 



DESCRIPTION 



SHORT DESCR 



FILENAME 



SRC DISK 



FNT WILDCRD 



AUX FILE 



FONT DISK 



A brief description of the device. This strings appears in the 
menus presented by GEM Setup. Maximum field length is 
80 characters. 

An even more brief description of the device. This string ap- 
pears below the device's icon in the GEM Output program. 
Maximum field length is 13 characters. See "Device Names" 
on at the end of this section. 

The filename for the device driver. This field is required. 
Maximum field length is 13 characters. 

The disk on which the driver is found. This string should 
match one of the string names listed under @HliAB__pTR in 
GEMSETUP.MSG. Maximum field length is 40 characters. 

A string in the form * . EXT that identifies the file extension 
used by the fonts associated with this device. Maximum 
field length is 40 characters. 

The filename (or names) of auxiliary files used by a printer. 
These are typically configuration or text mapping files. If 
this field lists more than one filename, the names are 
separated by a semi-colon. Maximum field length is 67 char- 
acters. 

The disk on which printer fonts are found. This string 
should match one of the string names listed under 
@HLAB_PTR in GEMSETUP.MSG. Maximum field length is 
40 characters. 



GEM/3 Programmers Toolkit Supplement 



11-5 



GEMSETUP.TXT 



MOUSE ID 



LONG DESCRP 



A unique one-byte code that identifies the mouse to the 
screen driver. The mouse ID occupies the second byte fol- 
lowing the string zyxg in the driver file. (The first byte is 
the mouse port — OOforCOMl, OlforCOMZ) Reserved 
mouse ID'S are: 

00 No mouse 

1 Mouse Systems'^'^ PC Mouse^^ / SummaMouse^'^ 
/ Compatibles 

02 Bus Mouse (Requires file MOUSE.COM) 
3 Microsoft Serial Mouse (RS232) 

4 SummaSketchTM 1201 Stylus-Type Tablet 

05 SummaSketch 1201 Cursor-Type Tablet 

6 SunnmaSketch 961 Stylus-Type Tablet 

7 SummaSketch 961 Cursor-Type Tablet 

8 SummagraphicsTM MM1812 Stylus-Type Tablet 

9 Summagraphics MM1812 Cursor-Type Tablet 

10 (hex OA) IBM® Personal System/2™ Mouse 

A long description of the device. This text is displayed 
when the user asks for help in GEM Setup. Maximum field 
length is 80 characters per line, with a maximum of 20 lines. 
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Device Names 

Ventura Publisher users can encounter an alert telling them that their printer 
and width table are incompatible, even though the width table is the correct 
one for the device. 

This supposed incompatibility arises when the SHORT DESCRin the printer 
driver does not match the device identification in the width table file. (This 
identification is actually the driver field from the printer's DDF file and has 
been embedded in the width table by Fontware.) Ventura compares the two 
values and, if they do not match, returns the alert. 

The alert is often more an annoyance than a sign of a true incompatibility. 
The user can ignore the alert if the incompatibility is simply a matter of in- 
consistencies in naming. For example, GEM printer drivers refer to the 
Hewlett-Packard LaserJet Series II as HP Laser 300, and Ventura drivers 
refer to it as HP LJ+, 300dpi. 

To avoid this alert, make sure the SHORT DESCR and driver values are the 
same. 
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